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Preface 



This publication is a guide to the use of 
the PL/I Optimizing Compiler (program No. 
5734-PLl) in a batch environment of the IBM 
Operating System. It explains how to use 
the compiler to execute PL/ I programs and 
describes the operating system features 
that may be required by a PL/I programmer. 
It does not describe the language 
implemented by the compiler, nor does it 
explain how to use the compiler in an 
operating system with the Time Sharing 
Option (TSO) ; these are the functions of 
the manuals listed under "Associated 
Publications, " below. 

The compiler is designed to operate 
under Release 20.1 of the IBM Operating 
System and under all subsequent releases 
and modifications unless otherwise stated 
in a revision of the Program Product 
Specifications. The compiler also operates 
under Release 1.0 and all subsequent 
releases of the Conversational Monitor 
System (CMS) component of the Virtual 
Machine Facility/370 (VM/370). 

An MFT, MVT, VSl, or VS2 version of the 
Operating System is required. Note that 
PL/I multitasking facilities can be used 
only on an MVT or VS2 system. 



basic concepts of data processing. These 
chapters introduce the reader to the 
operating system, and explain how tc run a 
PL/I program and how to define a data set. 



The rest of the manual certains rrcre 
detailed information on the optimizing 
compiler, and provides general guidance and 
reference information on operating system 
features that are likely tc be required by 
the PL/ I applications programmer. Most of 
this information is equally relevant to the 
use of the compiler in a batch or TSO 
environment. 



Chapter 4 describes the optimizing 
compiler, the data sets it requires, its 
optional facilities, and the listings it 
produces. Chapter 5 contains similar 
information for the linkage editor and 
loader, one of which is needed in addition 
to the compiler to prepare a PL/I program 
for execution. 

Chapters 6 through 10 are concerned with 
the various types of data sets that can be 
created and accessed by a PL/I program, and 
explain how to define these data sets. 



For execution of a PL/ I program, the 
optimizing compiler employs subroutines 
from the OS PL/I Resident Library (Program 
No. 5734-LM4) and the OS PL/I Transient 
Library (Program No. 5734-LM5) , and this 
programmer's guide assumes the availability 
of these program products. 

Different release levels of the OS PL/I 
Optimizing Compiler and the PL/I Resident 
and Transient libraries will be compatible 
in execution provided that the following 
conditions are satisfied: 

1. The release level of the transient 
library is equal to or greater than the 
release level of the resident library. 

2. The release level of the resident 
library is equal to or greater than the 
release level of the compiler. 

The first three chapters cover basic 
topics, and are intended primarily for 
casual (non-specialist) programmers or for 
newcomers to IBM system/ 360 or IBM 
System/370. The reader is assumed to have 
only an elementary grasp of PL/I and the 



Chapter 11 describes the standard 
cataloged procedures provided by IBM for 
the optimizing compiler, and explains how 
to modify them. 

Chapter 12 deals with the facilities 
available for debugging PL/I programs. 

Chapter 13 explains hew tc link programs 
written in PL/I with those written in 
assembler language. (The optimizing 
compiler implements language designed to 
facilitate communication between programs 
written in PL/I and those written in 
FORTRAN, COBOL, and ASSEMBLER; these 
facilities are described in the language 
reference manual listed under "Associated 
Publications," below.) 

Chapters 14 and 15 are concerned with 
the use of built-in subroutines included in 
the resident library to provide direct 
interface between PL/I programs and the 
operating system sort/merge and 
checkpoint/restart facilities. 

A series of appendixes supply sundry 
reference information. 



in 



Associated Publications 



The language implemented by the optimizing 
compiler is described in the following 
publication: 

OS PL/ I Optimizing and Checkout 
Compilers: Language Reference Manual , 
Order No. GC33-0009 

For information on how to use the 
compiler in a TSO environment refer to: 

OS Time Sharing Option: PL/I Optimizing 
Compiler , Order No. SC33-002 9 

For information on how to use the 
compiler under the Conversational Monitor 
System of VM/370, refer to: 

PL/I Optimizing Compiler: CMS User's 
Guide , Order No. SC33-0037 

The diagnostic messages issued by the 
compiler and the transient library are 
listed in the following publication, 
together with explanations, where 
necessary, and suggested programmer 
response: 

OS PL/ I Optimizing Compiler: Messages , 
Order No. SC33-0027 



OS Job Control Language Reference , 
Order No. GC28-6704 

OS Time Sharing Option , 
Terminal User's Guide , 
Order No. GC28-6763 

OS linkage Editor and loader . 
Order No. GC28-6538 

OS System Programmer's Guide , 
Order No. GC28-6550 

OS Utilities , Order No. GC28-6586 

OS Sort/Merge , Order No. SC28-6543 

OS Sort/Merge: Programmer's Guide , 
Order No. SC33-4 007 

OS/VS Sort/Merge: Programmer's Guide , 
Order Nc. SC33-4035 

OS Supervisor and Data Management Macro 
Instructions , Order No. GC28-6647 

OS Programmer's Guide t o Debugging , 
Order No.. GC28-6670 

I Terminal Commands and Compiler Options: 
| Reference Surrmary , Order Nc. SX33-6005 



Availability of Publications 



Recommended Publications 



The following publications are referred to 
in this programmer's guide. They contain 
additional details about particular topics 
discussed in this manual. 

OS PL/T Optimizing Compiler: 
Execution Logic , Order No. SC33-0025 

OS Introduction , 

Order No. GC28-6534 



The availability of a publication is 
indicated by its use key , the first letter 
in the order number. The use keys are 

G - General: available to users of IBM 

systems, products, and services 
without charge, in quantities to meet 
their normal requirements; can also be 
purchased by anyone through IBM branch 
offices. 

S - Sell: can be purchased by anyone 
through IBM branch offices. 
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Chapter 1: Introduction 



The Optimizing Compiler 



The PL/I Optimizing Compiler is a 
processing program that translates PL/I 
source programs, diagnosing errors as it 
does so, into IBM System/36 machine 
instructions. These machine instructions 
make up an object program. (Later in this 
chapter there is a description of how an 
object program is prepared for execution.) 

The compiler is designed to produce 
efficient object programs either with or 
without optimization. This optimization, 
which is optional, can be specified by the 
programmer by means of a compiler option. 
(See Chapter 4 for details.) 

If optimization is specified, the 
machine instructions generated will be 
optimized if necessary, to produce a very 
efficient object program. 

If optimization is not specified, 
compilation time will be reduced. 

The optimizing compiler can also be used 
conversationally. It can be invoked from a 
remote terminal to compile and execute a 
PL/I source program, and return the results 
to the terminal or to a printer. 

The optimizing compiler requires a 
minimum of 50K bytes of main storage when 
used with MFT and a minimum of 52K when 
used with MVT. (For minimum storage under 
OS/VS see Appendix G.) In any case it will 
work more efficiently with larger amounts 
of main storage. 



programs. The control prograir supervises 
the execution of all processing programs, 
and provides services that are required by 
the processing programs durirg their 
execution. The processing programs include 
such programs as compilers, the linkage 
editor, and the loader (described later in 
this chapter). The operating systeir is 
described in the publication OS 
Introduction . 

The optimizing compiler can be used with 
four operating system control prograirs: 

• MFT (Multiprogramming with a Fixed 
number of Tasks) permits up to fifteen 
jobs to be processed concurrently, each 
job occupying a separate area of main 
storage termed a partition . 

• MVT (Multiprogramming with a Variable 
number of Tasks) permits up to fifteen 
jobs to be processed concurrently, each 
job occupying a separate area of main 
storage termed a region . 

• VSl and VS2 (Virtual Storage) employ 
addressable auxiliary storage that 
appears to the user as main storage. In 
use VSl and VS2 are generally similar to 
MFT and MVT respectively; the 
differences are explained in Appendix G. 
Except as explained in the appendix, all 
information in this manual about M^T 
applies to VSl, and all information 
about MVT applies to VS2. 



TIME SHARING OPTION 



The Operating System 



The optimizing compiler must be executed 
through the IBM Operating System. This 
operating system is used with both 
System/360 and System/370. 

The operating system relieves the 
programmer of routine and time-consuming 
tasks by controlling the allocation of 
storage space and input/output devices. 
The throughput of the system is increased 
because the operating system can process a 
stream of jobs without intervention by the 
operator. 

The operating system comprises a control 
program and a number of processing 



An optional facility of the MVT operating 
system is the Time Sharing Option (TSO) . 
One or more regions can be allocated to TSO 
and several users can have concurrent 
access to the system. Each user enters his 
jobs from a remote terminal and can receive 
the results at the terminal. (To contrast 
it with this "conversational" mode of 
operation, the more conventional method of 
submitting jobs through the system operator 
is called batch operation .) 

This programmer's guide forms a complete 
guide to the use of the optimizing compiler 
in a batch environment. It also provides 
essential background and reference 
information for the TSO user; however, 
instructions on how to use TSO and how to 
use the optimizing compiler with TSO are 
contained in the publications TSO Terminal 
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User's Guide and TSO; PL/ 1 Optimizing 
Compiler . 



JOBS AND JOB STEPS 



In a batch environment, the order of 
processing jobs is determined by a user- 
defined job class and/or priority. Thus 
the order in which jobs are processed may 
differ from the order in which they are 
entered. Consequently jobs should be 
independent of each other. 

A job comprises one or more job steps , 
each of which involves the execution of a 
program. Since job steps are always 
processed one-by-one in the order in which 
they appear, they can be interdependent. 
For example, the output from one job step 
can be used as the input to a later one, 
and the processing of a job step can be 
made dependent on the successful completion 
of a previous job step. 



JOB CONTROL LANGUAGE 

Job control language (JCL) is the means by 
which a programmer defines his jobs and job 
steps to the operating system; it allows 
the programmer to describe the work he 
wants the operating system to do, and to 
specify the input /out put facilities he 
requires. 

Chapter 2, "How to Run a PL/I Program," 
illustrates the use of JCL statements that 
are essential for the PL/I programmer. 
Th€ise statements are: 

• JOB statement, which identifies the 
start of a job. 

• EXEC statement, which identifies a job 
step and, in particular, specifies the 
program to be executed, either directly 
or by means of a cataloged procedure 
(described later in this chapter) . 

• DD (data definition) statement, which 
defines the input/output facilities 
required by the program executed in the 
job step. 

• /* (delimiter) statement, which 
separates data in the input stream from 
the job control statements that follow 
this data. 

JOB, EXEC, and DD statements have the 
same format, and Figure 1-1 shows an 
example of a JOB statement on a punched 
card. These three statements are 



identified by the character sequence // in 
columns 1 and 2. Each statenent can 
contain four fields — name, operation, 
operand, and comments — that are separated 
by one or more blanks. The name field 
always starts in column 3. 

A full description of job control 
language is given in the publications OS 
Job Control Language User's Guide and OS 
Job Control Language Reference . 



Cataloged Procedures 



Regularly-used sets of job control 
statements can be prepared cnce, given a 
name, stored in a system library, and the 
name entered into the catalog for that 
library. Such a set of statements is 
termed a cataloged proc edure. A cataloged 
procedure comprises one or mere job steps 
(though it is not a job, because it must 
not contain a JOB statement) . it is 
included in a job by specifying its name in 
an EXEC statement instead of the name of a 
program. 

Several IBM- supplied cataloged 
procedures are available for use with the 
optimizing compiler. Chapter 11 describes 
these procedures and how to use them. 



EXECUTING A PL/I PROGRAM 

The process of executing a PL/I program 
requires a minimum of two jcb steps. 

A compilation job step is always 
required. In this step the optimizing 
compiler translates the PL/I source program 
into a set of machine instructions called 
an object module . This object module does 
not include all the machine instructions 
required to represent the source program. 
In many instances the compiler merely 
inserts references to subroutines that are 
stored in the OS PL/I Resident Library. 

To include the required subroutines from 
the resident library, the object module 
must be processed by one of two processing 
programs, the linkage editor and the 
loader, subroutines from the resident 
library may contain references to ether 
subroutines stored in the OS PL/i Transient 
Library. The subroutines frcm the 
transient library do not become a permanent 
part of the compiled program; they are 
loaded into main storage when needed during 
execution of the PL/I program, and the 
storage they occupy is released when they 
are no longer needed. 
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Figure 1-1. A JOB statement 



When using the linkage editor, two 
further job steps are required after 
compilation. In the first of these steps, 
the linkage editor converts the object 
module into a form suitable for execution, 
and includes subroutines, referred to by 
the compiler, from the resident library. 
The program in this form is called a load 
module . In the final job step, this load 
module is loaded into main storage and 
executed. 

When using the loader, only one more job 
step is required after compilation. The 
loader processes the object module, 
includes the appropriate library 
subroutines, and executes the resultant 
executable program immediately. 

Both the linkage editor and the loader 
can combine separately produced object 



modules and previously processed lead 
modules. However, they differ in one 
important respect: the linkage editcr 
produces a load module, which it always 
places in a library, where it can be 
permanently stored and called whenever it 
is required; the loader creates enly 
temporary executable programs in main 
storage, where they are executed 
immediately. 

The linkage editor also has several 
facilities that are not provided by the 
loader; for example, it can divide a 
program that is too large for the space 
available in main storage, sc that it can 
be loaded and executed segment by segment. 

The leader is intended primarily for use 
when testing programs and fcr processing 
programs that will be executed only once. 
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Chapter 2: How to Run a PL/ 1 Program 



The job control statements shown in Figure 
2-1 are sufficient to compile and execute a 
PL/I program that comprises only one 
external procedure. 

This program uses only punched-card 
input and printed output. For other forms 
of input/ output refer to Chapter 3. The 
listing produced includes only the standard 
default items. Many other items can be 
included by specifying the appropriate 
compiler options in the EXEC statement. 
The compiler listing and all the compiler 
options are described in Chapter 4. The 
linkage editor listing and the linkage 
editor options are described in Chapter 5. 
Appendix F is a sample PL/I program that 



includes most of the listing items 
discussed in these two chapters. 

The example in Figure 2-1 uses the 
cataloged procedure PLIXCLG. Several other 
cataloged procedures are supplied by IBM 
for use with the optimizing compiler (for 
example, for compilation only). The use of 
these other cataloged procedures is 
described in chapter 4. 

An alternative method of specifying 
compiler options is by use of the PROCESS 
statement, which is described in Chapter 4. 
An example of a PROCESS statement is : 

* PROCESS MACRO, OPT (TIME); 
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JOB statement 

EXAMPLE is the name of the job. You can use any name 
that does not have more than eight alphameric or national 
characters; the first character must not be numeric. The 
job name identifies the job within the operating system; it 
is essential. The parameters required in the JOB statement 
depend on the conventions established for your installation. 



EXEC statement 

PLIXCLG is the name of a cataloged procedure supplied by 
IBM. When the operating system meets this name, it replaces 
the EXEC statement with a set of JCL statements that have 
been written previously and cataloged in a system library. 
The cataloged procedure contains three procedure steps: 

PLI The compiler processes the PL/I program and translates 
it into a set of machine instructions called an object 
module. 

LKED The linkage editor produces a load module from the 
object module produced by the compiler. 

GO The load module produced by the linkage editor is 
loaded into main storage and executed. 



PL/ 1 source statements 



DD statement 

This statement indicates that the statements to be processed 
in procedure step PLI follow immediately in the card deck. 
SYSIN is the name that the compiler uses to refer to the 
device on which it expects to find this data. (In this case, 
the device is the card reader, and the data is the PL/I program.) 



-*• //EXAMPLE JOB (6487,N14),JONES,MSGLEVEL=1 
■*■ //STEP1 EXEC PLIXCLG 
■*• //PLI.SYSIN DD * 



EX001: PROCEDURE OPTIONS(MAIN); 

DECLARE (A,B,C) FIXED DECIMALS); 

ON ENDFILE(SYSIN) GO TO FINISH; 
NEXT: GETFILE{SYSIN)DATA(A,B); 

OA+B; 

PUT FILE(SYSPRINT)SKIP DATA(A,B,C); 

GO TO NEXT; 
FINISH: END; 



Delimiter statement 

This statement indicates the end of the data (that is, the 
PL/ 1 program). 



DD statement 

This statement indicates that the data to be processed by the 
program (in procedure step GO) follows immediately in the 
card deck. 



/* 

//GO.SYSIN DD 



A=131 B=75; 
A=2 B«907; 
A»- 14 8=14; 
A=341 B=429; 
A=245 B=102; 






N*K- 


Data to be processed 
by the PL/ 1 program 







Delimiter statement 

This statement indicates the end of the data. 



Figure 2-1. How to run a PL/I program 
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Chapter 3: How to Create and Access a Data Set 



Information 
Required 

Type of output 
device to which the 
data set will be 
transmitted. 

Serial number of the 
volume (tape reel, 
disk pack, etc.) 
that will contain 
the data set. 

Name of the data 
set. 



Parameter of 
DD statement 



UNIT= 



VOLUME=SER= 
(or VOL=SER=) 



DSNAME= (or DSN=) 



Type of records in DCB= (see appendix A) 

the data set. 

Amount of auxiliary SPACE= 
storage required for 
the data set 
(direct -access 
devices only) . 

Disposition of the DISP= 

data set on entry 
to, and at the end 
of the job step. 

Figure 3-1. Information to be 

specified when creating a 
data set 



A data set is any collection of data in 
auxiliary storage that can be created or 
accessed by a program. It can be punched 
onto cards or a reel of paper tape; or it 
can be recorded on magnetic tape or on a 
direct-access device such as a magnetic 
disk or drum. A printed listing can also 
be a data set, but it cannot be read by a 
program. 

Data sets that are created or accessed 
by PL/ I programs must have one of the 
following types of organization: 

CONSECUTIVE 

INDEXED 

REGIONAL 

Teleprocessing 

The items of data in a CONSECUTIVE data 
set are recorded in the order in which you 



present them, and can be accessed only in 
the order in which they were presented or, 
in the case of magnetic tape, in the 
reverse order. The items of data in 
INDEXED and REGIONAL data sets are arranged 
according to "keys" that you supply when 
you create the data sets. Teleprocessing 
data sets are organized as consecutive 
groups of data items. 

This chapter explains how to create and 
access CONSECUTIVE data sets stored en 
magnetic tape or on a direct-access device. 
It is intended to provide an introduction 
to the subject of data management, and to 
meet the needs of those programmers who do 
not require the full input/output 
facilities of PL/I and the operating 
system. Chapters 6 through 9 contain a 
full explanation of the relationship 
between the data management facilities 
provided by PL/I and these provided by the 
operating system, and they explain how to 
create and access all the types of data 
sets referred to above. 



Using a Data Set 



To create or access a data set, you must 
not only include the appropriate input and 
output statements in your PL/I program, but 
you must also supply certain information to 
the operating system in a DD statement. A 
DD statement defines a data set and 
specifies how it will be handled. The 
information contained in a DD statement 
enables the operating system to allocate 
the necessary auxiliary storage devices, 
and allows the compiler to use the data 
management routines of the operating system 
to transmit data between main storage and 
auxiliary storage. 

The language reference manual for this 
compiler describes the input and output 
statements that you will need to use in 
your PL/I program. Essentially, you must 
declare a file (explicitly or contextually) 
and open it (explicitly or implicitly) 
before you can begin to transmit data. A 
file is the means provided in PL/I for 
accessing a data set, and is related to a 
particular data set only while the file is 
open; when you close the file, the data set 
is no longer available to your program. 
This arrangement allows you to use the same 
file to access different data sets at 
different times, and to use different files 
to access the same data set. 
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| Parameters of DD Statement 


| When required | What you must state | Parameters 


| | Output device | UNIT= cr SYSOUT= 


| | Block size 1 | DCB=(BLKSIZE=. . . ) 


Direct access only | Always | Auxiliary storage | SPACE= 

j j space required | 


| Data set to be used | | 

j by another job step j Disposition | DISP= 

| but only required j j 

j by this job | | 


standard labeled j Data set to be kept | Disposition | DISP= 


| j Name of data set | DSN= 


j Data set to be on | Volume serial number | VOL=SER= 
j particular volume j j 



I 3 - Alternatively, you can specify the block size in your PL/I program by using the 
ENVIRONMENT attribute. 

L , J 

Figure 3-2. Creating a CONSECUTIVE data set: essential parameters of DD statement 



You must provide a DD statement for each 
data set that you will use in each job 
step. If you use the same data set in more 
than one job step, each job step that 
refers to this data set must include a DD 
statement for the data set. 

If you are using a cataloged procedure, 
such as PLIXCLG (described in Chapters 2 
and 10) , the DD statement for any data set 
processed by your program must be 
associated with the appropriate step of the 
procedure by qualifying the name of the DD 
statement with the name of the procedure 
step. For example: 



CONSECUTIVE data set. Figure 3-2 
summarizes this discussion. Figure 3-H is 
an example of creating this type of data 
set, and the sutparameters of the DCE 
parameter are described in Appendix A. The 
job control language reference publication 
explains how to code a DD statement. 



TYPE OF OUTPUT DEVICE (UNIT=) 



//GO. RESULTS DD . . . 

would indicate a DD statement named RESULTS 
in procedure step GO, as in the example in 
Figure 3-5. The name of the DD statement 
is known as its " ddname" . 



How to Create a Data Set 



The information that you should specify 
when you create a data set is listed in 
Figure 3-1, which also shows the parameters 
of the DD statement that you should use. 

The following paragraphs discuss the use 
of these parameters in creating a 



You must always indicate the type of output 
device (for example, magnetic tape or disk 
drive, card punch, or printer) on which you 
want to create your data set. Usually the 
simplest way to .do this is tc use the UNIT 
parameter, although for a printer or a card 
punch it is often more convenient tc use 
one of the special forms of DD statement 
discussed under "special -pur pose 
Parameters," later in this chapter. 

In the UNIT parameter, you can specify 
either the type number of the unit (for 
example, 2311 for a disk drive) or the name 
of a group of devices (for example, SYSDA 
for any direct- access device). The group 
names are established for a system during 
system generation. 
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VOLUME SERIAL NUMBER (VOLUME=SER=) 



LINESIZE option. 



A unit of auxiliary storage such as a reel 
of magnetic tape or a magnetic disk pack is 
termed a volume ; a volume can contain one 
or more data sets, and a data set can 
extend to more than one volume. A volume 
is identified by a serial number that is 
recorded within it (and usually printed on 
the label attached to it) . Although a deck 
of cards, a printed listing, and a reel of 
paper tape can be considered to be volumes, 
they do not have serial numbers. 

Specify a volume serial number only if 
you want to place the data set in a 
particular volume. If you omit the VOLUME 
parameter, the operating system will print 
in your program listing the serial number 
of the volume in which it placed the data 
set. 

The VOLUME parameter has several 
subparameters. To specify a volume serial 
number, you need only the SER (serial 
number) subparameter (for example, 
VOLUME=SER=12345) . 



NAME OF DATA SET (DSNAME=) 



You must name a new data set if you want to 
keep it for future jobs. If the data set 
is temporary (required only for the job in 
which it is created), you can still name 
it, but you need not; if you omit the 
DSNAME parameter, the operating system will 
assume that the data set is temporary* and 
will give it a temporary name. 
Alternatively, you can specify your own 
temporary name by prefixing it with the 
characters £S. For example: 

DSNAME=g&TEMP 

This is especially useful if you want to 
use the temporary data set in more than one 
step of your job. The cataloged procedures 
supplied with the optimizing compiler 
contain examples of such use. 



RECORD TYPE (DCB=) 



The type of record in a data set is 
defined by its format, its physical length 
( block size ) , and the length of the 
subsections (logical record l ength ) which 
together can be considered tc make up a 
physical record. 

The records in a data set must have one 
of the following formats! 

F fixed length 

V variable length (D- cr V-fcrirat) 

U undefined length 

F-, D-, and V-format records can be 
blocked (FB, DB, or VB) or unblocked (F, D, 
or V); V-format records can be spanned . (A 
spanned record is a record whose length can 
exceed the size of a block. If this 
occurs, the record is divided into segments 
and accommodated in two or more consecutive 
| blocks. D-format indicates that the record 
jis in an ASCII data set. (See the 
j language reference manual for this compiler 
| for details of ASCII data sets.) In most 
cases, you must specify a block size. If 
you do not specify a record length, 
unblocked records of length equal to the 
block size are assumed. If you are using a 
PRINT file to produce printed output, you 
do not need to specify a block size in your 
DD statement or in your PL/I program; in 
the absence of other information, the 
compiler supplies a default line size of 
120 characters. 

To give record -type information in a DD 
statement, use the RECFM (record format), 
BLKSIZE (block size) , and LRECL (logical 
record length) subparameters of the DCB 
parameter. The DCB parameter passes 
information to the operating system for 
inclusion in the data control block , a 
table maintained by the data management 
routines of the operating system for each 
data set in a job step; it contains a 
description of the data set and how it will 
be used. If your DCB parameter includes 
more than one subparameter, you must 
enclose the list in parentheses. For 
example: 

DCB=(RECFM=FB,BLKSIZE=1000,LRECL=50) 



You can give record-type information either 
in your PL/I program (in the ENVIRONMENT 
attribute or LINESIZE option) or in a DD 
statement. This discussion refers only to 
the DD statement, and does not apply if you 
decide to give the information in your 
program; refer to the language reference 
manual for this compiler for a description 
of the ENVIRONMENT attribute and the 



AUXILIARY STORAGE REQUIRED (SPACE=) 



When creating a data set on a direct-access 
device, you roust always specify the amount 
of auxiliary storage that the data set will 
need. Use the SPACE parameter to specify 
the number of cylinders, . tracks, or blocks 
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that the data set will need. If you intend 
to extend the data set in a later job or 
job step, ensure that your original space 
allocation is sufficient for future needs; 
you cannot make a further allocation later. 
If the SPACE parameter appears in a DD 
statement for a non-direct-access device, 
it is ignored. 



Except in the special case of data in 
the input stream (described under "Special- 
purpose Parameters, " later in this 
chapter) , you must always include the name 
of the data set (DSNAME) and its 
disposition (DISP) . 



TYPE CF INPUT DEVICE (UNIT=) 



DISPOSITION OF DATA SET (DISP=) 



To keep a data set for use in a later job 
step or job, you must use the DISP 
parameter to specify how you want it to be 
handled. You can pass it to another job 
step, keep it for use in a later job, or 
enter its name in the system catalog. If 
you want to keep the data set, but do not 
want to include its name in the system 
catalog, the operating system will request 
the operator to demount the volume in which 
it resides and keep it for you. If you 
omit the DISP parameter, the operating 
system will assume that the data set is 
temporary and will delete it at the end of 
the job step. 

The DISP parameter can contain two 
positional subparameters. The first 
specifies whether the data set is new or 
already exists, and the second specifies 
what is to be done with it at the end of 
the job step. If you omit the first, you 
must indicate its absence by a comma. For 
example: 

DISP=(,CATLG) 

specifies that the data set is to be 
cataloged at the end of the job step. The 
omission of the first subparameter means 
that the data set is assumed by default to 
be new. 



You can omit the UNIT parameter if the data 
set is cataloged or if it is created with 
DISP= (NEW, PASS) in a previous job step of 
the same jot. Otherwise, it must always 
appear. (PASS specifies that the data set .. 
is to be passed for use by a subsequent job 
step in the same job) . 



VOLUME SERIAL NUMBER (VOLUME=SER=) 



You can omit the VOLUME parameter if the 
data set is cataloged or if it is created 
with DISP=(,FASS) in a previous job step of 
the same job. Otherwise it must always 
appear. 



NAME CF DATA SET (DSNAME=) 



The DSNAME parameter can either refer back 
to the DD statement that defined the data 
set in a previous job step, cr it can give 
the actual name of the data set. (Ycu 
would have to use the former method to 
refer to an unnamed temporary data set.) 



RECORD TYPE (DCB=) 



How to Access a Data Set 



To access (that is, read or update) an 
existing data set, your DD statement should 
include information similar to that given 
when the data set is created. However, for 
data sets on labeled magnetic tape or on 
direct-access devices, you can omit several 
parameters because the information they 
contain is recorded with the data set by 
the operating system when the data set is 
created; Figure 3-3 summarizes the 
essential information and Figure 3-5 is an 
example of accessing this type of data set. 
The subparameters of the DCB parameter are 
described in Appendix A, and the job 
control language reference publication 
explains how to code a DD statement. 



You can omit the DCB parameter if the 
record information is specified in your 
PL/ I program, using the ENVIRONMENT 
attribute, or if you are accessing a data 
set on a direct-access device or standard 
labeled magnetic tape, otherwise ycu roust 
specify the DCB parameter for punched 
cards, paper tape, or unlabeled magnetic 
tape. 



AUXILIARY STORAGE REQUIRED (SPACE=) 



You cannot add to, or otherwise modify, the 
space allocation made for a data set when 
it is created. Accordingly, the SPACE 
parameter is never required in a DE 
statement for an existing data set. 
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Parameters of DD statement 



When required 




| What you must state 


Parameters 


Always 




[Name of data set 


DSN= 


Disposition of data set 


DISP= 


|A11 devices 




Input device 


UNIT= 


cataloged j Magnetic tape 
| direct access 


and 


| Volume serial number 


VOL=SER= 


For punched cards, paper tape, 
unlabeled magnetic tape 


or 


| Elcck size 1 


DCB=(BLKSIZE=. ..) 



^Alternatively, you can specify the block size in your PL/I program by using the 
(ENVIRONMENT attribute. 

L • J 

Figure 3-3. Accessing a CONSECUTIVE data set: essential parameters of DD statement 



DISPOSITION OF DATA SET (DISP=) 



Except for unit record devices (such as 
card readers) , you must always include the 
DISP parameter to indicate to the operating 
system that the data set exists. Code 
DISP=SHR if you want to read the data set, 
DISP=OLD if you want to read and/cr 
overwrite it, or DISP=MOD if you want to 
add records to the end of it. 



the type of device. The usual convention 
is for class A to refer to a printer and 
class B to a card punch; the IBM-supplied 
cataloged procedures assume that this 
convention is followed. 

To route your output through a system 
output device, use the SYSOUT parameter in 
your DD statement. For example, to punch 
cards, use the DD statement: 

//GO. PUNCH DD SYSOUT-B 



Special-purpose Parameters 



Three parameters of the DD statement have 
special significance because you can use a 
very simple form of DD statement; they are; 

SYSOUT= 

* 

DATA 

SYSOUT= is particularly useful for printed 
or punched-card output, and * and DATA 
allow you to include data in the input 
stream. 



System Output (SYSOUT=) 



A system output device is any unit (but 
usually a printer or a card punch) that is 
used in common by all jobs. The computer 
operator allocates all the system, output 
devices to specific classes according to 



Data in the Input Stream (* and DATA) 



A convenient way to introduce data to your 
program is to include it in the input 
stream with your job control statements. 
Data in the input stream must, like job 
control statements, be in the form of 8 0- 
byte records (usually punched cards) , and 
must be immediately preceded by a DD 
statement with the single parameter * in 
its operand field. For example: 

//GO.SYSIN DD * 

To indicate the end of the data, you may 
optionally include a delimiter job control 
statement (/*) . If you omit the /* 
delimiter, the end of the data is 
determined by the next job control 
statement (commencing // in the first two 
columns) in the input stream. 

If your data includes records that start 
with // in the first two columns use the 
parameter DATA. For example: 
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//OPT3#4 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
CREATE: PROC OPTIONS (MAIN) ; 

DCL PUNCH FILE STREAM OUTPUT, 

DISK FILE RECORD OUTPUT SEQUENTIAL, 
1 RECORD, 

2(A,B,C,X1, X2) FLOAT DEC ( 6) COMPLEX; 

ON ENDFILE(SYSIN) GO TO FINISH; 

OPEN FILE(PUNCH), FILE(DISK); 
NEXT: GET FILE(SYSIN) LIST(A,B,C); 

Xl=(-B+SQRT(B**2-4*A*C))/(2*A) ; 

X2=(-B-SQRT(B**2-4*A*C))/(2*A) ; 

PUT FILE (PUNCH) EDIT (RECORD) (C (E (16 ,9) ) ) ; 

WRITE FILE(DISK) FROM ( RECORD ) ; 

GO TO NEXT; 
FINISH: CLOSE FILE (PUNCH) , FILE (DISK); 

END CREATE; 
/* 

//GO. PUNCH DD SYSOUT=B 

//GO. DISK DD DSN=R00TS,UNIT=2311,V0L=SER=D186,DISP=(NEW,KEEP), 
// SPACE=(TRK, (1, 1)),DCB=(RECFM=FB,BLKSIZE=4 00,LRECL=40) 

//GO.SYSIN DD * 
5 12 4 

4 -10 4 

5 16 2 

4 -12 10 

5 12 9 
29 -20 4 
/* 

Figure 3-4. Creating a CONSECUTIVE data set 



//OPT3#5 JOB 
//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
ACCESS: PROC OPTIONS (MAIN) ; 

DCL RESULTS FILE RECORD INPUT SEQUENTIAL, 
1 RECORD, 

2(A,B,C,X1, X2) FLOAT DEC(6) COMPLEX; 

ON ENDFILE (RESULTS) GO TO FINISH; 

PUT FILE (SYSPR INT) EDIT ( *A' , f B ' , f C • , *X1 • , 'X2 ') 

(X(7),3(A,X(23)),A,X(22),A); 
OPEN FILE (RESULTS) ; 
NEXT: READ FILE (RESULTS) I NT 0( RECORD) ; 

PUT FILE(SYSPRINT) SKIP EDIT(RECORD) (C (F (12 ,2) ) ) ; 
GO TO NEXT; 
FINISH: CLOSE FILE (RESULTS) ; 
END ACCESS; 
/* 
//GO. RESULTS DD DSN=ROOTS, UNIT=2311, V0L=SER=D186,DISP= (OLD, KEEP) 

Figure 3-5. Accessing a CONSECUTIVE data set 
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//GO. SYS IN DD DATA 

In this case, you must always indicate 
the end of the data by the job control 
delimiter statement (/*). 



Standard Files 



Examples 



Two examples of simple applications for 
CONSECUTIVE data sets are shown in Figures 
3-4 and 3-5; both use the cataloged 
procedure PLIXCLG supplied by IBM. 



PL/I includes two standard files, SYSIN for 
input and SYSPRiNT for output. If your 
program includes a GET statement without 
the FILE or STRING option, the compiler 
uses the file name SYSIN; if it includes a 
PUT statement without the FILE option, the 
compiler uses the name SYSPRINT. 

If you use one of the IBM- supplied 
cataloged procedures to execute your 
program, you will not need to include a DD 
statement for SYSPRINT; procedure step GO 
always includes the statement: 

//SYSPRINT DD SYSOUT=A 

The block size is normally supplied by 
the compiler; you need not specify it 
yourself, unless you want blocked output. 

If your program uses SYSIN, either 
explicitly or implicitly, you must always 
include a corresponding DD statement. 



The first program evaluates the familiar 
expression for the rcots of a quadratic 
equation and stores the results in a data 
set on a disk pack and on punched cards. 
[The last but one DD statement 
(//GO. DISK. . . ) specifies that the newly 
created data set is to be given the name 
ROOTS and is to be stored in a volume with 
serial number D186 on a 2311 Disk Stcrage 
Drive. It specifies that fixed-length 
records, 40 bytes in length, are to be 
grouped together in blocks, each 400 bytes 
long. It specifies that the data set is 
new and that it is to be kept en the voluire 
at the end of the job step; and it 
specifies that one track of the disk 
storage drive is to be allocated to the 
data set with one additional track tc be 
used if more space is required. 

The second program accesses the data set 
on the disk pack created in the first 
program and prints the results. 
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Chapter 4: The Compiler 



This chapter describes the optimizing 
compiler and the job control statements 
required to invoke it, and defines the data 
sets it uses. It describes the compiler 
options, the listing produced by the 
compiler, batched compilation, and the 
preprocessor, all of which are introduced 
briefly below. 

The optimizing compiler translates the 
PL/I statements of the source prograir into 
machine instructions. A set of machine 
instructions such as is produced for an 
external PL/I procedure by the compiler is 
termed an object module . If several sets 
of PL/I statements, each set corresponding 
to an external procedure and separated by 
appropriate control statements, are 
present, the compiler can create two or 
more object modules in a single job step. 

However, the compiler does not generate 
all the machine instructions required to 
represent the source program. Instead, for 
frequently used sets of instructions such 
as those that allocate main storage or 
those that transmit data between irain 
storage and auxiliary storage, it inserts 
into the object module references to 
standard subroutines. These subroutines 
are stored either in the OS PL/I Resident 
Library or in the OS PL/I Transient 
Library. 

An object module produced by the 
compiler is not ready for execution until 
the appropriate subroutines from the 
resident library have been included; this 
is the task of either one of two processing 
programs, the linkage editor and the 
loader, described in chapter 5. An object 
module that has been processed by the 
linkage editor is referred to as a load 
module ; an object module that has been 
processed by the loader is referred to as 
an executable program . 

Subroutines from the transient library 
do not form a permanent part of the load 
module or executable program. Instead, 
they are loaded as required during 
execution, and the storage they occupy is 
released when they are no longer needed. 

While it is processing a PL/I program, 
the compiler produces a listing that 
contains information about the program and 
the object module derived from it, together 
with messages relating to errors or other 
conditions detected during compilation. 
Much of this information is optional, and 
is supplied either by default or by 



specifying appropriate cpticrs when the 
compiler is invoked. 

The compiler also includes a 
preprocessor (or compile-time processor) 
that enables you to ircdify source 
statements or insert additicr.al scurce 
statements before compilation commences. 

Compiler options, discussed under 
"Optional Facilities," later in this 
chapter, can be used for purposes ether 
than to specify the information to be 
listed. For example, the preprocesscr can 
be used independently to process source 
programs that are to be compiled later, or 
the compiler can be used rrerely tc check 
the syntax of the statements of the source 
program. Also, continuation cf processing 
through syntax checking and compilation can 
be made conditional on successful 
preprocessing. 



Description of the Compiler 



The compiler consists of a number of load 
modules, referred to as phases, each of 
which can be loaded individually intc irain 
storage for execution. A simplified flow 
diagram is shown in Figure 4-1. The first 
phase tc be loaded is a resident control 
phase , which remains in main storage 
throughout compilation. This phase 
consists of a number cf service routines 
that provide facilities required during 
execution of the regaining phases. One of 
these routines communicates with the 
supervisor program of the operating system 
for the sequential loading of the remaining 
phases, which are referred tc as processing 
phases . 



The resident control phase alsc causes a 
transient control phase to be loaded, the 
function of which is tc initialize the 
operating environment in accordance with 
options specified by the prcgrairmer. 

Each processing phase perfcrirs a single 
function or a set of related functions. 
Some of these phases irust be leaded and 
executed for every compilation; the 
requirement for other phases depends on the 
content of the source program or on the 
optional facilities selected. Apart from 
the phases that provide diagnostic 
information, each phase is executed ence 
only. 
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SOURCE TEXT 

[FROM SYSIN) 




MACRO 



NOMACRO 



BCDorCHARSET(48) ^ HARArTFR- 

SET 



48- 

CHARACTER- 
SET 
PROCESSOR 



60-CHARACTER-SET 
TEXT VIA SYSUT1 




EBCDIC or 
CHARSET(60) 



COMPILE- 
TIME PRE- 
PROCESSOR 



SYNTAX- 
ANALYSIS 
STAGE 



PROCESSED SOURCE 
TEXT VIA SYSUT1 



DICTIONARY- 
BUILD 
STAGE 



TRANSLATION 
STAGES 



FINAL- 
ASSEMBLY 
STAGE 



OBJECT MODULE 
(TO SYSLIN OR SYSPUNCH) 



Figure 4-1. simplified flow diagram of the compiler 
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Input to the compiler is known 
throughout all stages of the compilation 
process as text . Initially, this text 
comprises the PL/I statements of the source 
program. At the end of compilation, it 
comprises the machine instructions 
substituted by the compiler for the source 
text, together with the inserted references 
to resident library subroutines for use by 
the linkage editor or by the loader. 

The source text must be in the form of a 
data set defined by a DD statement with the 
name SYSIN; frequently, this data set is a 
deck of punched cards. The source text is 
passed to the syntax- analysis stage either 
directly or after processing by one of the 
following preprocessor phases: 

1. If the source text is in the PL/I 48- 
character set or in BCD, the 48- 
character-set preprocessor translates 
it into the 60-character set. To use 
the 48 -character- set processor, 
specify the CHARSET(48) or 
CHARSET(BCD) options. 

2. If the source text contains 
preprocessor statements, the 
preprocessor executes these statements 
in order to modify the source text or 
to introduce additional statements. 
Also, if the source text is in the 
PL/I 4 8- character set or in BCD (as 
specified by the CHARSET.C48) or 
CHARSET(BCD) options) , the 
preprocessor automatically translates 
it into the 60-character set. To use 
the preprocessor, specify the MACRO 
compiler option. 

Both preprocessor phases store the 
translated source text in the data set 
defined by the DD statement with the name 
SYSUTl . 

The syntax-analysis stage takes its 
input either from this data set or from the 
data set defined by the DD statement with 
the name SYSIN. This stage analyzes the 
syntax of the PL/ I statements and removes 
any comments and non- significant blank 
characters. 

After syntax analysis, the dictionary- 
build stage creates a dictionary containing 
entries for all identifiers in the source 
text. The compiler uses this dictionary to 
communicate descriptions of the elements of 
the source text and the object module 
between phases. The dictionary- build stage 
of the compiler replaces all identifiers 
and attribute declarations in the source 
text with references to dictionary entries. 

Further processing of the text involves 
several compiler stages, known as 
translation stages, which: 



• Translate the text from the PL/I 
syntactic form into an internal 
syntactic form. 

• Rearrange the text to facilitate further 
translation (for exairple, by replacing 
array assignments with do-loops that 
contain element assignments) . 

• Map arrays and structures tc ensure 
correct boundary alignment. 

• Translate the text into a series of 
fixed-length tables, each with a format 
that can be used to define machine 
instructions. 

• Allocate main storage for static 
variables and generate inline code to 
allow storage to be allocated 
automatically during execution. (In 
certain cases resident library 
subroutines may also be called to 
allocate storage during execution.) 

The final -assembly stage translates the 
text tables into machine instructions, and 
creates the external symbol dictionary 
(ESD) and relocation dictionary (RLE) 
required by the linkage editor and by the 
loader. 

The external symbol dictionary includes 
the names of subroutines that are referred 
to in the object module but are net part of 
the module and that are to be included by 
the linkage editor or by the leader; these 
names, which are termed external 
references , include the names of all the 
PL/I resident library subroutines that will 
be required when the object irodule is 
executed. (These resident library 
subroutines may, in their turn, contain 
external references to other resident 
library subroutines required for 
execution) . 

The relocation dictionary contains 
information that enables absolute storage 
addresses to be assigned to locations 
within the load module when it is leaded 
for execution. 

The external symbol dictionary and the 
relocation dictionary are described in 
Chapter 5, which also explains how the 
linkage editor and the loader use them. 



Job Control Statements for Compilation 



Although you will probably use cataloged 
procedures rather than supply all the job 
control statements required for a job step 
that invokes the compiler, you should be 
familiar with these statements so that you 
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Standard 
ddname 


Contents of 
data set 


Possible 

device 
classes 


Record 
format 
(RECFM) 


Record 

size 
(LRECL) | 


Buffers 


BUFNO | BLKSIZE 


SYSIN (or 
SYSCIN) 


Input to the 
compiler 


SYSSQ 


F,FB,U 
VB,V 


<101(100) | 
<105(104) | 


2 


2 00 


SYSLIN 


Object module 


SYSSQ 


FB 


80 | 


2 


80 


SYSPUNCH 


Preprocessor 
output, 
compiler output 


SYSSQ 
SYSCP 


FB 


80 | 


2 


80 


SYSUTl 


Temporary 
workf ile 


SYS DA 


F 


1091,1691,3491| 
or 4051 | 
according to | 
available j 
space 






SYSPRINT 


Listing, 

including 

messages 


SYSSQ 


VBA 


125 | 


2 


129 


SYSLIB 


Source 

statements for 
preprocessor 


SYS DA 


F,FB 


<101 | 

1 


— 


~ 



Notes: 



The possible device classes are: 

SYSSQ Magnetic-tape or direct-access device. 

SYSDA Direct-access device. 



SYSCP 



Card -punch device. 



Any block size can be specified except for SYSLIB and SYSUTl. Block size 
for SYSLIB depends on the options specified. If the INCLUDE option is 
specified, the maximum block size is 4260 bytes. If MACRO is specified, 
for SIZE values below 60K bytes, the maximum is 400 bytes; above 60K 
bytes, the block size maximum is the value of LRECL for SYSUTl. The 
block size for SYSUTl is always provided by the compiler. 

If the record format is not specified in a DD statement, the default value 
(underlined) is provided by the compiler. 

The compiler will attempt to obtain source input from SYSCIN if a DD 
statement for this data set is provided. Otherwise it will obtain its 
input from SYSIN. 

The numbers in parentheses in the "Record size" column are the defaults 
which can be overridden by the user. Where no parentheses are present, 
the value is fixed and cannot be altered. 



Figure 4-2. compiler standard data sets 
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can make the best use of the compiler, and 
if necessary, override the statements of 
the cataloged procedures. 

The IBM-supplied cataloged procedures 
that include a compilation procedure step 
are as follows : 

PLIXC Compile only. 

PLIXCL Compile and link-edit. 

PLIXCLG Compile, link- edit, and execute. 

PLIXCG Compile, load, and execute. 

The following paragraphs describe the 
essential job control statements for 
compilation. The IBM-supplied cataloged 
procedures are described in Chapter 11 and 
include examples of these statements. 



EXEC STATEMENT 

The basic EXEC statement is: 

//stepname EXEC PGM=IELOAA 

The PARM parameter of the EXEC statement 
can be used to specify one or more of the 
optional facilities provided by the 
compiler. These facilities are described 
under "Optional Facilities, " later in this 
chapter. 



Input (SYSIN, or SYSCIN) 



Input tc the compiler must be a data set 
defined by a DD statement with the name 
SYSIN or SYSCIN; this data set must have 
CONSECUTIVE organization. The input must 
be one or more external FL/I procedures; if 
you want to compile mere than one external 
procedure in a single jot or job step, 
precede each procedure, except possibly the 
first, with a PROCESS statement (described 
under "Eatched Compilation," later in this 
chapter) . 

Eighty-column punched cards are commonly 
used as the input medium for PL/I source 
programs. However, the input data set may 
be on a direct-access device, magnetic 
tape, or paper tape. The input data set 
may contain either fixed-length records, 
blocked or unblocked,, variable-length 
records, or undefined-length records? the 
maximum record size is 100 bytes. The 
compiler always reserves 200 bytes of main 
storage (100 bytes each) for two buffers 
for this data set; however, you may specify 
a block size of more than 10C bytes,, 
provided that sufficient main storage is 
available to the compiler. (See the 
discussion of the SIZE option under 
"Optional Facilities," later in this 
chapter . ) 



Output (SYSLIN, SYS PUNCH) 



DD STATEMENTS FOR THE STANDARD DATA 
SETS 



The compiler requires several standard data 
sets, the number depending on the optional 
facilities specified. You must define 
these data sets in DD statements with the 
standard ddnames which are shown, together 
with other characteristics of the data 
sets, in Figure 4-2. The DD statements 
SYSIN, SYSUTl, and SYSPRINT are always 
required. 

You can store any of the standard data 
sets on a direct-access device, in which 
case, you must include the SPACE parameter 
in the DD statement that defines the data 
set to specify the amount of auxiliary 
storage required. The amount of auxiliary 
storage allocated in the IBM-supplied 
cataloged procedures should suffice for 
most applications. 



Output (that is, one or more object 
modules) from the compiler can be stored in 
either the data set defined by the DD 
statement with the name SYSLIN (if ycu 
specify the OBJECT compiler option) or in 
the data set defined by the ED statement 
with the name SYSPUNCH ( if you specify the 
DECK compiler option). You may specify 
both options in one program, when the 
output will be stored in both data sets. 

The object module is always in the form 
of 80-byte fixed-length records, blocked or 
unblocked. The compiler always reserves 
two buffers of 80 bytes each; however, you 
may specify a block size of mere than 80 
bytes, provided that sufficient main 
storage is available to the compiler. (see 
the discussion of the SIZE option under 
"Optional Facilities," later in this 
chapter.) The data set defined by the DD 
statement with the name SYSPUNCH is also 
used to store the output from the 
preprocessor if you specify the MDECK 
compiler option. 
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T emporary Workfile (SYSUTl) 



The compiler requires a data set for use as 
a temporary workfile. It is defined by a 
ED statement with the name SYSUTl, and is 
known as the spill file . It must be on a 
direct- access device. The spill file is 
used as a logical extension to main storage 
and is used by the compiler and by the 
preprocessor to contain text and dictionary 
information. 

Four record sizes are given in Figure 
4-2 for SYSUT1 . For storage devices other 
than the 333 0, the first three sizes 
correspond to the amount of storage 
available to the compiler, as shown in 
Figure 4-3. 



specify those parts that ycu require by 
including the appropriate compiler options. 
The information that may appear, and the 
associated compiler options, are described 
under "Compiler Listing, " later in this 
chapter. 

You must define the data set in which 
you wish the compiler to store its listing 
in a ED statement with the name SYSPRINT. 
This data set must have CONSECUTIVE 
organization. Although the listing is 
usually printed, it can be stored en any 
magnetic-tape or direct-access device. For 
printed output, the following statement 
will suffice if your installation follows 
the convention that output class A refers 
tc a printer: 

//SYSPRINT DD SYSCUT=A 



Storage 

50-55K 
56-69K 
over 6 9K 



Record Siz e 

1091 
1691 
3491 



Figure 4-3. Record sizes for SYSUTl 



The compiler always reserves 258 bytes 
of main storage (129 bytes each) for two 
buffers for this data set; however, you may 
specify a block size of more than 129 
bytes, provided that sufficient irain 
storage is available to the compiler. (See 
the discussion of the SIZE option under 
"Optional Facilities," later in this 
chapter. ) 



A record size of 4 051 is used en the 
3330. 

Note that the DD statements given in 
this publication and in the cataloged 
procedures for SYSUTl request a space 
allocation in blocks of 1024 bytes; this is 
to ensure adequate secondary allocations cf 
direct-access storage space are acquired. 

Dedicated Data Sets : If a job being run 
under MVT has several job steps, and each 
job step requires a data set for use as a 
temporary workfile, the result is a 
considerable overhead in time and space. 
To reduce this as far as possible, you can 
use dedicated data sets . These are data 
sets that are created by the operating 
system when the job is selected for 
processing. They can be used by each job 
step that requires a temporary workfile. 
Dedicated data sets are normally allocated 
by the initiator and deleted when it 
terminates. More information on using 
dedicated data sets is given in chapter 11. 



Li sting (SYSPRINT) 



Source Statement Library (SYSLIE) 



If you use the preprocessor 5SINCLUEE 
statement to introduce source statements 
into the PI/I program from a library, you 
can either define the library in a DD 
statement with the name SYSLIE, or ycu can 
choose your own ddname (or ddnames) and 
specify a ddname in each ^INCLUDE 
statement. (See "Ccmpile-time Processing," 
later in this chapter.) 



EXAMPIE CF COMPILER JCL 



A typical sequence of job control 
statements for compiling a FL/I program is 
shown in Figure 4-4. The DECK and NCOBJECT 
compiler options, described below, have 
been specified to obtain an object module 
as a card deck only. Job control 
statements for link editing an object 
module in the form cf a card deck are shown 
in Chapter 5. 



The compiler generates a listing that 
includes all the source statements that it 
processed, information relating to the 
object module, and, when necessary, 
messages. Most of the information included 
in the listing is optional, and ycu can 



Optional Facilities 



The compiler provides a number of optional 
facilities, both at compile time and at 
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//COMP JOB 

//STEP1 EXEC PGM=IEL0AA,PARM='EECK,NOOEJECT' 

//SYSPUNCH DB SYSOUT=B 

//SYSUT1 DD UNIT=SYSBA ,SPACE= (1024 , (60 , 60) , , CONTIG) 

//SYSPRINT BB SYSOUT=A 

//SYSIN BB * 



(insert here the PL/I program to be compiled) 



/* 

Figure 4-4. Typical job control statements for compiling a FI/I program 



execution time. Options that can be 
specified at compile time are known as 
compiler options . Options that can be 
specified at execution time are known as 
execution-time options . 

Execution-time and compiler options, 
their abbreviated forms, and their defaults 
(as supplied by IBM) are shown in Figures 
4-5 and 4-7. An installation can modify or 
delete defaults according to local 
requirements? check for any modified 
defaults at your installation. Beleted 
compiler options can be reinstated for a 
compilation by means of the CONTROL 
compiler option. 

| Also provided is the ability to pass an 
j argument to the PL/I main procedure. This 
J facility is described in the section 
("Specifying Execution -Time Options in the 
|EXEC Statement," later in this chapter. 



SPECIFYING COMPILER OPTIONS 



For each compilation, the IBM or 
installation default for a compiler option 
will apply unless it is overridden by 
specifying the option in a PROCESS 
statement or in the PARM parameter of an 
EXEC statement. 

An option specified in the PARM 
parameter overrides the default value, and 
an option specified in a PROCESS statement 
overrides both that specified in the PARM 
parameter and the default value. 

Where conflicting attributes are 
specified either explicitly or implicitly 
by the specification of other options, the 
latest implied or explicit option is 
accepted. No diagnostic message is issued 
to indicate that any options are overridden 
in this way. 



Specifying Compiler Options in the EXEC 
Statement 



Tc specify options in the EXEC statement, 
code FARtf= followed by the list cf options, 
in any crder (except that CONTROL, if used, 
must be first) separating the options with 
commas and enclosing the list within single 
quotation marks, for example: 



//STEF1 EXEC FGN=IEIOAA,FARM= 'OBJECT, LIST' 

Any option that has quotation marks, for 
example KARGINI Cc 1 ) , must have the 
quotation marks duplicated. The length of 
the option list must not exceed 256 
characters, including the separating commas 
(note that only the first 100 characters 
are printed out on the listing). However, 
many of the options have an abbreviated 
form that ycu can use to save space. If 
you need to continue the statement cnto 
another line, you must enclose the list of 
options in parentheses (instead cf in 
quotation marks) enclose the options list 
on each line in quotation marks, and ensure 
that the last comma on each line except the 
last is outside of the quotation marks. An 
example covering all the above points is as 
follows: 

//STEF1 EXEC FGK=IEL0£a,FARM=(•AG,A , , 
|// , C,ESB,F(I) ,FLOW(lC,l) f , 
// 'M,MI( M X'' • ),NEST,STG,X*) 

If ycu are using a cataloged procedure, 
and wish to specify options explicitly, ycu 
must include the PARM parameter in the EXEC 
statement that invokes it,, qualifying the 
keyword PARN. with the name of the procedure 
step that invokes the compiler, for 
example: 

//STEF1 EXEC FIIXCLG^ARW.PLI^A^IS^ESE' 
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I Specifying Compiler Options in the 
PROCESS Statement 



To specify options in the PROCESS 
statement, code as follows: 

* PROCESS options; 

where "options" is a list of compiler 
options. The list of options must be 
terminated with a semicolon and should not 
extend beyond the default right-hand source 
margin. The asterisk must appear in the 
first byte of the record (card column 1), 
and the keyword PROCESS may follow in the 
next byte (column) or after any number of 
blanks. Option keywords must be separated 
by a comma and/or at least one blank. 

Blanks are permitted before and after 
any non-blank delimiter in the list, with 
the exception of strings within quotation 
marks, for example MARGINK • *• ) , in which 
optional blanks should not be inserted. 

The number of characters is limited only 
by the length of the record. If you do net 
wish to specify any options, code: 

* PROCESS; 

Should it be necessary to continue the 
PROCESS statement onto the next card or 
record, terminate the first part cf the 
list after any delimiter, up to the default 
right-hand margin, and continue on the next 
card or record. Option keywords or keyword 
arguments may be split, if required, when 
continuing onto the next record, provided 
that the keyword or argument string 
terminates in the right-hand source margin, 
and the remainder of the string starts in 
column 1 of the next record. A PROCESS 
statement may be continued in several 
statements, or a new PROCESS statement 
started. 



The following paragraphs describe the 
options in alphabetic order. For those 
options that specify that the compiler is 
to list information, enly a brief 
description is included; the generated 
listing is described under "Compiler 
Listing," later in this chapter. 

Figure 4-5 lists all the compiler 
options with their abbreviated forms and 
their standard default values for batch 
mode. Defaults under TSO are given in the 
TSO User's Guide for this ccirpiler. 



AGGREGATE Option 



The AGGREGATE option specifies that the 
compiler is to include in the compiler 
listing an aggregate length table, giving 
the lengths of all arrays and major 
structures in the source program. 



ATTRIBUTES Cption 



The ATTRIBUTES option specifies that the 
compiler is to include in the compiler 
listing a table of source-program 
identifiers and their attributes. If both 
ATTRIBUTES and XREF apply, the two tables 
are combined. 



CHARSET Option 



The CHARSET option specifies the character 
set and data code that you have used to 
create the source program. The compiler 
will accept source programs written in the 
6 0-character set or the 18 -character set, 
and in the Extended Einary Coded Decimal 
Interchange Code (EBCDIC) or Binary Coded 
Decimal (BCD). 



COMPILER OPTIONS 



The compiler options are of the following 
types: 

1. Simple pairs of keywords: a positive 
form (for example, NEST) that requests 
a facility, and an alternative 
negative form (for example, NONEST) 
that rejects that facility. 

2. Keywords that permit you to provide a 
value-list that qualifies the option 
(for example, NCCOMPILE(E) ) . 

3. A combination of 1 and 2 above. 



60- or 18-character se t: If the source 
program is written in the 6C-character set, 
specify CHARSET (60); if it is written in 
the 48-character set, specify CHARSET(48) . 
The language reference manual for this 
compiler lists both of these character 
sets. (The compiler will accept source 
programs written in either character set if 
CHARSET (18) is specified, however, if the 
reserved keywords, for example, CAT or LE 
are used as identifiers, errors may occur.) 

BCD or EBCDIC : If the source program is 
written in BCD, specify CHARSET (ECD); if it 
is written in EBCDIC, specify 
CHARSET (EBCDIC) . The language reference 
manual for this compiler lists the EBCDIC 
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Compiler Option 



| Abbreviated Name 



IBM Default 



AGGREGATE | NOAGGREGATE 

ATTRIBUTES | NOATTRIBUTES 

CHARSET([48|60] [EBCDIC | BCD] ) 

COMPILE | NOCOMPILEt (W|E|S) ] 

CONTROL ( * pa ssword ' ) 

COUNT | NOCOUNT 

DECK | NODECK 

DUMP) NOD UMP 

ESD JNOESD 

FLAG[ (I |W|E|S)] 

FLOWt (n ,m) ] j NOFLOW 

GONUMBER| NOGONUMBER 

GOSTMT|NOGSTMT 

IMPRECISE j NOIMPRECISE 

INCLUDE j NOINCLUDE 

INSOURCE | NOINSOURCE 

LINECOUNT(n) 

LISTE (n,m)] | NOLIST 

LMESSAGE | SMESSAGE 

MACRO|NOMACRO 

MAP|NOMAP 

MARGINI ( 'c ' ) | NOMARGINI 

MARGINS (m,n[,c]) 



MDECKJNOMDECK 

NAME ('name') 

NEST|NONEST 

NUMBER | NONUMBER 

OBJECT | NOOB JECT 

OFFSET | NOOFFSET 

OPTIMIZE (TIME | 0|2) | NOOPTIMIZE 

OPTIONS | NOOPTIONS 

SEQUENCE (m,n) | NOSEQUENCE 

si ze ( [ - ] yyyyyyyy | [ -] yyyyyK | max) 

SOURCE ) NOSOURCE 

STMT|NOSTMT 

STORAGE | NOSTORAGE 

SYNTAX | NOSYNTAX [ (W | E | S ) ] 

TERMINAL[ (opt-list) ] j NOTERMINAL 

XREF i NOXREF 



AG | NAG 

A|NA 

CS(U8|60] [EB|B]) 

C|NC[ (W|E|S)3 


CT|NCT 
D|ND 


DU 1 NDU 



F[ (I|W|E|S)3 

GN|NGN 
GS | NGS 
IMP | N IMP 
INCJNINC 
IS|NIS 
LC(ri) 

LMSG|SMSG 
MjNM 

MK'c') |NMI 
MAR(m,n[,c]) 



MD|NMD 
N ( ' name * ) 

NUM | NNUM 

OBJ j NOBJ 

OF|NOF 

OPT(TIME|0|2) |NOPT 

OP | NOP 

SEQ(m r n) |NSEQ 

s z ( [ - ] yyyyyyyy 1 1 - 1 yyyyyK | max ) 

S|NS 

STG | NSTG 

SYN|NSYN[ (W|E|S)] 
TERM[ (opt-list)] |NTERM 
XI NX 



NOAGGREGATE 
NOATTRIBUTES 
CHARSET(60 EBCDIC) 
NOCOMPILE(S) 

NOCOUNT 
NODECK 

NOESD 

FLAG (I) 

NOFLOW 

NOGONUMBER 

NOGOSTMT 

NOIMPRECISE 

NOINCLUDE 

INSOURCE 

LINECOUNT(55) 

NOLIST 

LMESSAGE 

NOMACRO 

NOMAP 

NOMARGINI 

MARGINS (2, 72,0) or 

MARGINS (10,100,0) 

(see text) 

NOMDECK 

NONEST 

NONUMBER 

OBJECT 

NOOFFSET 

NOOPTIMIZE 

OPTIONS 

NOSEQUENCE 

SIZE (MAX) 

SOURCE 

STMT 

NCSTCPAGE 

NOSYNTAX (S) 

NOTERMINAL 

NOXREF 



Figure 4-5. Compiler options, abbreviations, and defaults in batch ircde 



representation of both the 48-character set 
and the 6 0-character set. 

If both arguments (4 8 or 60, EBCDIC or 
BCD) are specified, they may be in any 
order and should be separated by a blank or 
by a comma. 



during preprocessing or syntax checking. 
The NOCOMPILE option without an argument 
causes processing to stop unconditionally 
after syntax checking, with an argument, 
continuation depends on the severity of 
errors detected so far, as follows: 



COMPILE Option 



NOCOMPIIE(W) No compilation if a warning, 
error, severe error, or 
unrecoverable error is 
detected. 



The COMPILE option specifies that the 
compiler is to compile the source program 
unless an unrecoverable error was detected 



NOCOMPILE (E) No compilation if error, 

severe error, cr unrecoverable 
error is detected. 
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NOCOMPILE(S) No compilation if a severe 

error or unrecoverable error 
is detected. 

If the compilation is terminated by the 
NOCOMPILE option, the cross-reference 
listing and attribute listing may be 
produced; the other listings that follow 
the source program will not be produced. 



DUMP Option 



The DUMP option specifies that the compiler 
is to produce a formatted dump of main 
storage if the compilation terminates 
abnormally (usually due to an I/O error or 
compiler error) . This duirp is written on 
the data set associated with SYSPRINT. 



CONTROL Option 



The CONTROL option specifies that any 
compiler options deleted for your 
installation are to be available for this 
compilation. You must still specify the 
appropriate keywords to use the options. 
The CONTROL option must be specified with a 
password that is established for each 
installation; use of an incorrect password 
will cause processing to be terminated. 
The CONTROL option, if used, must be 
specified first in the list of options. It 
has the format: 

CONTROL ( ' pas sword ■ ) 

where "password" is a character string, not 
exceeding eight characters. 



COUNT Option 



The COUNT option specifies that the 
compiler is to produce code to enable the 
number of times each statement is executed 
to be counted at execution time. 

The COUNT option implies the GOSTMT 
option if the STMT option applies, or the 
GONUMBER option if the NUMBER option 
applies. 



ESP Option 



The ESD option specifies that the external 
symbol dictionary (ESD) is tc be listed in 
the compiler listing. 



FLAG Option 



The FLAG option specifies the minimum 
severity of error that requires a rr ess age 
to be listed in the compiler listing. The 
format of the FLAG option is given in 
Figure 4-6. 



FLAG (I) List all iressages. 

FLAG(W) List all except inforiratory 
messages. If you specify 
FLAG, FLAG(W) is assuired. 

FLAG(E) List all except warning and 
inf ormatory iressages . 

FLAG(S) List only severe error and 
unrecoverable error 
messages . 

Figure 4-6. Format of the FLAG option 



FLOW Option 



DECK Option 



The DECK option specifies that the compiler 
is to produce an object module in the form 
of 80- column card images and store it in 
the data set defined by the DD statement 
with the name SYSPUNCH. Columns 73-76 of 
each card contain a code to identify the 
object module; this code comprises the 
first four characters of the first label in 
the external procedure represented by the 
object module. Columns 77-80 contain a 4- 
digit decimal number: the first card is 
numbered 0001, the second 0002, and so on. 



The FLOW option specifies that the compiler 
is to produce code to enable the flow of 
control to be listed when the prograir is 
executed. The format of the FLOW option 
is: 



FLOW[(n,m)] 



where "n 1 



is the maxiirurr nuirber cf 
entries to be included in the 
lists. It should net exceed 
32768. 



'm" is the maximum number of 

procedures for which the lists 
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are to be generated. It 
should not exceed 32768 . 



| at suitable points in your prcgrair, 



The IBM default, if (n,m) is not 
specified, is (25,10). 

The output produced by the FLOW option 
is described under "Execution-Time FLOW 
Option" later in this chapter. 



GONUMBER Option 



The GONUMBER option specifies that the 
compiler is to produce additional 
information that will allow line numbers 
from the source program to be included in 
execution-time messages. Alternatively, 
these line numbers can be derived by using 
the offset address, which is always 
included in execution-time messages, and 
the table produced by the OFFSET option. 
(The NUMBER option must also apply.) 

Use of the GONUMBER option implies 
NUMBER, NOSTMT, and NOGOSTMT. 



INC LUDE Option 



The INCLUDE option requests the compiler to 
handle the inclusion of PL/I source 
statements for programs that use the 
^INCLUDE statement. Fcr prcgrairs that use 
the % INCLUDE statement but no other PL/I 
preprocessor statements, this method is 
faster than using the preprocessor. If the 
MACRO option is also specified, the INCLUDE 
option has no effect. 



I NSOURCE Option 



The INSOURCE option specifies that the 
compiler is to include a listing of the 
source program (including preprocessor 
statements) in the compiler listing. This 
option is applicable only when the 
preprocessor is used, therefore the MACRO 
option must also apply. 



GOSTMT Option 



The GOSTMT option specifies that the 
compiler is to produce additional 
information that will allow statement 
numbers from the source program to be 
included in execution -time messages. 
Alternatively, these statement numbers can 
be derived by using the offset address, 
which is always included in execution-time 
messages, and the table produced by the 
OFFSET option. (The STMT option must also 
apply . ) 

Use of the GOSTMT, NOGONUMBER option 
implies STMT and NONUMBER. 



LINECOUN T Option 



The LINECOUNT option specifies the number 
of lines to be included in each page of the 
compiler listing, including heading lines 
and blank lines. The format of the 
LINECOUNT option is: 

LINECOUNT (n) 

where "n" is the nuirber cf lines. It 

must be in the range 1 through 
3 2767, but cnly headings are 
generated if you specify less 
than 7. 



IMPRECISE Option 



LIST Option 



The IMPRECISE option specifies that the 
compiler is to include extra text in the 
object module to localize imprecise 
interrupts when executing the program with 
an IEM System/360 Model 91 or 195 (see 
|Appendix D) . This extra text is generated 
j for ON statements (to ensure that if 
j interrupts occur, the correct on-units will 
jbe entered), for null statements, and fcr 
j ENTRY statements. The correct line or 
j statement numbers will not necessarily 
j appear in execution-time messages. If you 
I need more accurate identification of the 
j statement in error , insert null statements 



The LIST optioa specifies that the compiler 
is to include a listing cf the object 
module (in a form similar tc IEM System/360 
assembler language instructions) in the 
compiler listing. The fcrmat cf the list 
option is: 

LIST[(m[,n])] 

where "m" is the number of the first source 
statement for which an object listing is 
required and "n" is the number of the last 
source statement for which an object 
listing is required. If "n" is omitted. 
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only statement "m" is listed. If the 
option NUMBER applies, "m" and "n n must be 
specified as line numbers. 



LMESSAGE Option 



The LMESSAGE and SMESSAGE options specify 
that the compiler is to produce messages in 
a long form (specify LMESSAGE) or in a 
short form (specify SMESSAGE). Short 
messages can have advantages in a TSO 
environment due to the comparatively slow 
printing speed of a terminal. 



MACRO Option 

The MACRO option specifies that the source 
program is to be processed by the 
preprocessor. 



MAP Option 



The MAP option specifies that the compiler 
is to produce tables showing the 
organization of the static storage for the 
object module. These tables consist of a 
static internal storage map and the static 
external control sections. The MAP option 
is normally used with the LIST option. 



MARGINI Option 



The MARGINI option specifies that the 
compiler is to include a specified 
character in the column preceding the left- 
hand margin, and in the column following 
the right-hand margin of the listings 
resulting from the INSOURCE and SOURCE 
options. Any text in the source input 
which precedes the left-hand margin will be 
shifted left one column, and any text that 
follows the right-hand margin will be 
shifted right one column. For variable- 
length input records that do not extend as 
far as the right-hand margin, the character 
is inserted in the column following the end 
of the record. Thus text outside the 
source margins can be easily detected. 

The MARGINI option has the format: 

MARGINI (*c') 

where "c" is the character to be printed 
as the margin indicator. 



MARGINS Option 



The MARGINS option specifies the extent of 
the part of each input line cr record that 
contains PL/I statements. The compiler 
will not process data that is outside these 
limits (tut it will include it in the 
source listings). 

The option can also specify the position 
of an American National Standard (ANS) 
printer control character tc format the 
listing produced if the SOURCE option 
applies. This is an alternative tc using 
XPAGE and XSKIP statements (described in 
the language reference manual fcr this 
compiler). If you do not use either 
method, the input records will be listed 
without any intervening blank lines. The 
format of the MARGINS option is: 

MARGINS (m,n[,c]) 

where" "in" is the column number of the 
left-hand margin. It should 
| not exceed 100. 

"n" is the column number of the 
right-hand margin. It should 
be greater than m, but not 
| greater than 100. 

"c" is the column number of the 

ANS printer control character. 
J It should not exceed 100 and 

should be outside the values 
specified for m and n. Only 
the following control 
characters can be used: 

(blank) Skip one line before printing. 

Skip two lines before printing. 
Skip three lines before printing. 

+ No skip before printing. 

1 Start new page. 

The standard IBM-supplied default for 
| fixed- length records is MARGINS (2,72,0) ; 
jthat for variable-length and undefined- 
| length records is MARGINS (1 0,100,0). A 

zero value for "c" specifies that there is 

no printer control character. 



MDECK Option 



The MDECK option specifies that the 
preprocessor is to produce a copy of its 
output (see MACRO option) and store it in 
the data set defined by the DD statement 
with the name SYSPUNCH. The last fcur 
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bytes of each record in SYSUTl are not 
copied, thus this option allows you to 
retain the output from the preprocessor as 
a deck of 8 0-column punched cards. 



NAME Option 



The NAME option specifies that the compiler 
is to place a linkage editor NAME statement 
as the last statement of the object module. 
When processed by the linkage editor, this 
NAME statement indicates that primary input 
is complete and causes the specified naire 
to be assigned to the load module created 
from the preceding input (since the last 
NAME statement) . 

It is required if you want the linkage 
editor to create more than one load module 
from the object modules produced by batched 
compilation (see later in this chapter). 

If you do not use this option, the 
linkage editor will use the member name 
specified in the DD statement defining the 
load module data set. You can also use the 
NAME option to cause the linkage editor to 
substitute a new load module for an 
existing load module with the same name in 
the library. The format of the NAME option 
is: 

NAME ( * name ' ) 

where "name" has from one through eight 
characters, and begins with an 
alphabetic character. The 
linkage editor NAME statement 
is described in Chapter 5 . 



NEST Option 



The NEST option specifies that the listing 
resulting from the SOURCE option will 
indicate, for each statement, the block 
level and the do-group level. 



NUMBER Option 



by NOSTMT or GCNUMBER. 

The position of the sequence field can 
be specified in the SEQUENCE option. 
Alternatively the following default 
positions are assumed: 

• First 8 columns for undefined-length or 
variable-length source input records. 
In this case, 8 is added to the values 
used in the MARGINS option. 

• Last 8 columns for fixed-length source 
input records. 

These defaults are' the positions used 
for line-numbers generated by TSO; thus it 
is not necessary to specify the SEQUENCE 
option, or change the MARGINS defaults, 
when using line numbers generated by TSO. 
Note that the preprocessor output has 
fixed- length records irrespective of the 
original primary input. Any sequence 
numbers in the primary input are 
repositioned in columns 73-8 0. 

The line number is calculated from the 
five right-hand characters of the sequence 
number (or the number specified, if less 
than five) . These characters are converted 
to decimal digits if necessary. Each time 
a sequence number is found that is not 
greater than the preceding line number, a 
new line number is formed by adding the 
minimum integral multiple of 100,000 
necessary to produce a line number that is 
greater than the preceding one. If the 
sequence field consists only of blanks, the 
new line number is formed by adding 10 to 
the preceding one. The maximum line number 
permitted by the compiler is 134,000,000; 
numbers that would normally exceed this are 
set to this maximum value. Only eight 
digits are printed in the source listing; 
line numbers of 100,000,000 or over will be 
printed without the leading "1" digit. 

If there is more than one statement on a 
line, a suffix is used to identify the 
actual statement in the messages. for 
example, the second statement beginning on 
the line numbered 4 will be identified by 
the number 40.2. The maximum value for 
this suffix is 31. Thus the thirty-first 
and subsequent statements on a line have 
the same number. 



The NUMBER option specifies that the 
numbers specified in the sequence fields in 
the source input records are to be used to 
derive the statement numbers in the 
listings resulting from the AGGREGATE, 
ATTRIBUTES, LIST, OFFSET, SOURCE and XREF 
options. 

If NONUMBER is specified, STMT and 
NOGONUMBER are implied. NUMBER is implied 



OBJECT Option 



The OBJECT option specifies that the 
compiler is to store the object module that 
it creates in the data set defined by the 
DD statement with the name S^SLIN. 
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OFFSET Option 



OPTIONS Opt i on 



The OFFSET option specifies that the 
compiler is to print a table of statement 
or line numbers for each procedure with 
their offset addresses relative to the 
primary entry point of the procedure. This 
information is of use in identifying the 
statement being executed when an error 
occurs and a listing of the object module 
(obtained by using the LIST option) is 
available. If GOSTMT applies, statement 
numbers, as well as offset addresses, will 
be included in execution-time messages. If 
GONUMBER applies, line numbers, as well as 
offset addresses, will be included in 
execution-time messages. 

A method of determining statement or 
line numbers from the offsets given in 
error messages is given under the heading 
"Statement Offset Addresses" later in this 
chapter. 



The OPTIONS option specifies that the 
compiler is to include in the compiler 
listing, a list showing the compiler 
options, to be used during this 
compilation. This list includes all those 
applied by default, those specified in the 
PARM parameter of an EXEC statement, and 
those specified in a PROCESS statement. 



SEQUENCE Option 



The SEQUENCE option specifies the extent of 
the part of each input line or record that 
contains a sequence number. This nurrber is 
included in the source listings produced by 
the INSOURCE and SOURCE option. Also, if 
the NUMBER option applies, line numbers 
will be derived from these sequence numbers 
and will be included in the source listings 
in place of statement numbers. No attempt 
is made to sort the input lires or records 
into the specified sequence. The SEQUENCE 
option has the format: 



SEQUENCE (m,n) 



OPTIMIZE Option 



where "m" specifies the column number of 
the left-hand margin. 



The OPTIMIZE option specifies the type of 
optimization required: 



"n" specifies the column nuirber of 
the right-hand margin. 



NOOPTIMIZE specifies fast compilation 

speed, but inhibits 
optimization for faster 
execution and reduced main 
storage requirements. 

OPTIMIZE specifies that the 

(TIME) compiler is to optimize the 

machine instructions 
generated to produce a very 
efficient object program. A 
secondary effect of this 
type of optimization can be 
a reduction in the amount of 
main storage required for 
the object module. The use 
Of OPTIMIZE (TIME) could 
result in a substantial 
increase in compile time 
over NOOFTIMIZE. 

OPTIMIZE (0) is the equivalent of 
NOOPTIMIZE. 

OPTIMIZE (2) is the equivalent of 
OPTIMIZE (TIME) . 

The language reference manual for this 
compiler includes a full discussion of 
optimization. 



The extent specified should not overlap 
with the source program (as specified in 
the MARGINS option). 



SIZE Option 



This option can be used to limit the amount 
of main storage used by the compiler. This 
is of value, for example, when dynanically 
invoking the compiler, to ensure that space 
is left for other purposes. The SIZE 
| option can be expressed in five forms: 



size (yyyyyyyy) 



SIZE(yyyyyK) 



size (-yyyyyy) 



specifies that yyyyyyyy 
bytes of main storage are 
to be requested. Leading 
zeros are not required. 

specifies that yyyyyK bytes 
of main storage are to be 
requested (1K=1024). 
Leading zeros are net 
required. 

specifies that the compiler 
is to obtain as much main 
storage as it can, and then 
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SIZE(-yyyK) 



SIZE (WAX) 



release yyyyyy bytes to the 
operating system. Leading 
zeros are not required. 

specifies that the compiler 
is to obtain as much main 
storage as it can, and then 
release yyyK bytes to the 
operating system (1K=1024) . 
Leading zeros are not 
required. 

specifies that the compiler 
is to obtain as much main 
storage as it can . 



The IBM default, and the most usual 
value to be used, is SIZE (MAX) , which 
permits the compiler to use as much main 
storage in the partition or region as it 
can. 



compilation, the value established when the 
compiler is invoked cannot te changed for 
later programs in the batch. Thus it is 
ignored if specified in a PROCESS 
statement. 

In a TSO environment, an additional 10K 
to 30K bytes must be allowed for TSO. The 
actual size required for TSO depends on ; 
which routines are placed in the link-pack 
area (a common main storage pool available 
to all regions). 



SMESSAGE Option 



See LMESSAGE option. 



When a limit is specified, the amount of 
main storage used by the compiler depends 
on how the operating system has been 
generated, and the method used for storage 
allocation. The compiler assumes that 
buffers, data management routines, and 
processing phases take up a fixed amount of 
main storage, but this amount can vary 
unknown to the compiler. 

| The negative forms can be useful when a 
I certain amount of space must be left free 
jand the maximum size is unknown, or can 
I vary because the job is run in regions of 
j different sizes. 

Under MFT the compiler will operate in a 
partition of 50 K bytes or more of main 
storage, using its default values for file 
specifications. Under MVT a region of 5 2K 
bytes or more is required. 

After the compiler has loaded its 
initial phases and opened all files, it 
attempts to allocate space for working 
storage. 

If SIZE (MAX) is specified it obtains all 
space remaining in the region or partition 
(after allowance for subsequent data 
management storage areas) . If a limit is 
specified then this amount is requested. 
If the amount available is less than 
specified, but is more than the minimum 
workspace required, compilation proceeds. 
If insufficient storage is available, 
compilation is terminated. This latter 
situation should arise only if the region 
or partition is too small, that is, less 
than 50K, or if too much space for buffers 
has been requested. The value cannot 
exceed the main storage available for the 
job step and cannot be changed after 
processing has begun. 

This means , that in a batched 



SOURCE Option 



The SOURCE option specifies that the 
compiler is to include in the compiler 
listing a listing of the source program, 
The source program listed is either the 
original source input or, if the MACRO 
option applies, the output from the 
preprocessor. 



STMT Option 



The STMT option specifies that statements 
in the source program are to be counted, 
and that this "statement number" is used tc 
identify statements in the compiler 
listings resulting from the AGGREGATE, 
ATTRIBUTES, LIST, OFFSET, SOURCE, andXREF 
options. STMT is implied by NONUMBER or 
GOSTMT. If NCSTMT is specified, NUMEER and 
NOGOSTMT are implied. 



STORAGE Option 



The STORAGE option specifies that the 
compiler is to include in the compiler 
listing a table giving the main storage 
requirements for the object ircdule. 



SYNTAX Option 



The SYNTAX option specifies that the 
compiler is to continue into syntax 
checking after initialization (or after 
preprocessing if the MACRO option applies) 
unless an unrecoverable error is detected. 
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The NOSYNTAX option without an argument 
causes processing to stop unconditionally 
after initialization (or preprocessing). 
With an argument, continuation depends en 
the severity of errors detected so far, as 
follows: 



The other options that relate to the 
listing (that is, FLAG, GONUMBER, GOSTMT, 
LINECCUKT, IKESSAGE/SNESSAGE, MARGINI, 
NEST, and NUMBER) will be the same as for 
the SYSPRINT listing. 



NOSYNTAX (W) 



NOSYNTAX (E) 



NOSYNTAX (S) 



No syntax checking if a 
warning, error, severe 
error, or unrecoverable 
error is detected. 

No syntax checking if an 
error, severe error, or 
unrecoverable error is 
detected. 

No syntax checking if a 
severe error or 
unrecoverable error is 
detected. 



If the SOURCE option applies, the compiler 
will generate a source listing even if 
syntax checking is not performed. 

If the compilation is terminated by the 
NOSYNTAX option, the cross-reference 
listing, attribute listing, and other 
listings that fellow the source program 
will not be produced. 

The use of this option can prevent 
wasted runs when debugging a PL/I program 
that uses the preprocessor. 



TERMINAL Option 



The TERMINAL option is applicable only in a 
ISO environment. It specifies that soire cr 
all of the compiler listing produced during 
compilation is to be printed at the 
terminal. If TERMINAL is specified without 
an argument, diagnostic and infcriratory 
messages are printed at the terminal. You 
can add an argument, which takes the form 
of an option list, to specify other parts 
of the compiler listing that are to be 
printed at the terminal. 

The listing at the terminal is 
independent of that written on SYSPRINT. 
However, if SYSPRINT is associated with the 
terminal, only one copy of each option 
requested will be printed even if it is 
requested in the TERMINAL option and also 
as an independent option. The following 
option keywords, their negative forms, or 
their abbreviated forms, can be specified 
in the option list: 

AGGREGATE, ATTRIBUTES, ESD, INSOURCE, 
LIST, MAP, OPTIONS, SOURCE, STORAGE, 
and XREF. 



XREF Option 



The XREF option specifies that the compiler 
is to include in the compiler listing a 
list cf all identifiers used in the PL/I 
program together with the nuirbers cf the 
statements in which they are declared or 
referenced. Note that label references on 
END statements are not included, reference 
lists for structures may be inccirplete, and 
arrays cf structures are always listed with 
bounds of (*). If both ATTRIBUTES and XREF 
apply, the two tables are combined. 



SPECIFYING EXECUTION-TIME OPTIONS 



For each execution, the IBM or installation 
default for an executicn-tiite cpticn will 
apply unless it is overridden by a PIIXOPT 
string in the source prcgrair cr by the PARM 
parameter of the EXEC statement for the 
execution step. 

An option specified in the PLIXOPT 
string overrides the default value, and an 
option specified in the FARM paraireter 
overrides that specified in the PLIXOPT 
string. 



Specifying Execution-Tiire Options in 
the PLIXOPT String 



Execution-time options can be specified in 
a source program by means of the following 
declaration: 

DCL PLIXOPT CHAR(len) VAR INITCstrg*) 
STATIC EXTERNAL; 

where "strg" is a list of options 
separated by commas, and "ler" is a 
[constant equal to or greater than the 
length cf "strg". 

If more than one external procedure in a 
job declares PLIXOPT as STATIC EXTERNAL, 
only the first string will be link-edited 
and available at execution time;. 

The PIIXCPT string is ignored in a 
Checkout Compiler/Optimizing Compiler 
mixture environment. 
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I Specifying Execution-Time Options in 
the EXEC Statement 



The method of coding the PARM parameter in 
an EXEC statement is given under the 
heading "Specifying Compiler Options in the 
EXEC Statement" earlier in this chapter. 

If you are using a cataloged procedure, 
you must qualify the keyword PARM with the 
name of the execution step; for example: 

//STEP EXEC PLIXCLG,PARM.GO=('ISA(10K) • , 
// REPORT) 

You can also use the PARM field to pass 
an argument to the PL/I main procedure. To 
do so, place the argument, preceded by a 
slash, after the execution -time options. 
For example: 

//GO EXEC PGM=OPT,PARM='ISASIZE(10K) , 
// REPORT /ARGUMENT' 

If you wish to pass an argument without 
specifying options, it must be preceded by 
a slash. For example: 

//GO EXEC PG M= OPT, PARM='/ ARGUMENT' 



EXECUTION -TIME OPTIONS 



| The following paragraphs describe the 
| execution-time options, which can be 
j specified in the EXEC statement or in the 
JPLIXOPT string. 

COUNT specifies that a count is to be 
kept of the number of times each 
statement in the program is 
executed and that the results are 
to be printed when the program 
terminates. This option is 
discussed in greater detail under 
the heading "Execution -Time COUNT 
Option" later in this chapter. 

NOCOUNT specifies that statement counting 
is not to be performed. 

FLOW[(n,m)3 specifies that a list of the 
most recent transfers of control 
in the execution of the program is 
to be generated. This option is 
discussed in greater detail under 
the heading "Execution-Time FLOW 
Option" later in this chapter. 

NOFLOW specifies that a flow list is not 
to be produced. 

ISASIZE specifies the amount of main 

storage initially acquired by the 
PL/ I program at execution time. 



This storage is known as the 
initial storage area (ISA) . The 
option has the format: 

ISASIZE (([ x] [ # y] [,z]) i< ; L ,:•'.■-.■ 

where "x" is the initial storage 
allocation for the major task, 

where "y" is the initial storage 
allocation for each subtask within 
the total storage available to the 
compiler. This value can te used 
in a multitasking program to 
prevent a new storage request 
(with its accompanying time 
overhead) each time a block is 
entered during the execution of 
the subtasks. If you specify 
enough storage for a whole 
subtask, these additional requests 
are not made, 

and where "z" is the maximum 
number of subtasks that will be 
active at any one time. 

All storage values must be in 
bytes or K bytes. If "x" is 
omitted and "y" or "z" is 
specified, or if "y" is omitted 
and "z" is specified, then the 
separating commas must be used to 
indicate that a value is missing. 

If the multitasking arguments ("y" 
and "z") are specified for a 
program that was linkedited 
without the multitasking library, 
they will be ignored, and a 
diagnostic message will be issued. 

The ISA is used for the dynamic 
allocation of the main storage 
required by PL/I blocks as they 
are entered, and by controlled and 
based variables as they are 
allocated. If the ISA is large 
enough to contain these blocks 
PL/I storage handling will not 
acquire any more storage from the 
system. 

If ISASIZE is not specified, then 
in a non -multi tasking environment 
the IBM default value is 
calculated as fellows: 

(m - n)/2 

where "m" is the region size for 
the GO step, and "n" is the load 
module length. This value is 
rounded up to a 2K toundary. In a 
multitasking environment, the 
default is 8K bytes for the major 
task and 8K bytes for each 
subtask. The default value for 
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REPORT 



the maximum number of active 
subtasks is 20. 

Note that if an initial storage 
allocation is too large, that is, 
most variables in STATIC and few 
controlled and based allocations, 
there will be a considerable 
amount of wasted main storage in 
the ISA. In some cases this may 
cause the program to terminate 
abnormally, because there is 
insufficient storage available for 
dynamically-loaded modules and fcr 
data areas required by the 
operating system. 

If the initial storage allocation 
is too small, then dynamic main 
storage requirements will be less 
efficiently met by individual 
requests to the system. 
Furthermore, the defaults may not 
appear in the storage report given 
by the REPORT option. If a 
default ISASIZE is used initially 
and proves to be too small, then 
the ISASIZE finally used, which 

appears in the ^w Ml.1 j appear t» ±u 

^3re- report, may be less than the 
default. For instance in a 
multitasking environment the major 
task's ISASIZE will default to 8K 
bytes. If this task has an 
AUTOMATIC character string 
variable of say 20K bytes the ISA 
will be too small. Certain 
control blocks are placed first in 
the ISA and occupy about IK bytes 
of it. The DSA, which will be 
greater than 2 OK because it 
includes storage for automatic 
variables, is then allocated. 
Since there is no room for it in 
the ISA, more storage is made 
available from the remainder of 
the region. However to avoid 
wastage of storage the unused part 
of the ISA is freed beforehand. 
Thus the length of the initial 
storage allocation will te 
approximately IK bytes and this 
length will be printed in the 
report. 

The execution -time option REPORT 
is available to enable the 
programmer to determine exactly 
what his storage requirements are, 
apart from I/O requirements. 

specifies that a report of certain 
program management activity is to 
be printed. The report will be 
automatically output to a data set 
with the ddname PLIDUMP cr PL1DUMP 
on program termination. This 
includes, for example, the amount 



of storage that was specified in 
the ISASIZE option, the length of 
the initial storage area, and the 
amount of PL/I storage required. 
This option may be abbreviated to 
R. The use of the report is 
described in "Execution-time 
Storage Requirements", below. 

NOREPORT specifies that a report is not 
required. This cpticn may he 
abbreviated to NR. 

STAE specifies that when an AEENE 

occurs, the PL/I library routines 
are to attempt to raise the ERROR 
condition or to produce a 
diagnostic message and a PLIDUMP. 

NOSTAE specifies that on program 

initialization, a S1AE macrc 
instruction is not to be issued. 

SPIE specifies that when a program 

interrupt occurs, the PL/I error 
handler is to be invoked. Under 
certain circumstances the ERROR 
condition will be raised. 

NOSPIE specifies that on program 

initialization, a SPIE macro 
instruction is not to be issued. 
This option must net be used if 
extended precision variables are 
used in the PL/I source program. 

The execution -time options are discussed 
in greater detail in the publication OS 
PL/I Op timizing Compiler : Execution L oqi c . 



Execution -time Storage Requirements 



At execution time there are three separate 
areas of main storage. 

The first area is the load module. Its 
length can be obtained from the linkage 
editor output listing. 

The second area is the initial storage 
area (ISA). Its length can be specified by 
the ISASIZE execution- time option or 
supplied by default. If supplied by 
default in a non-multitasking environment, 
it will be approximately half of the main 
storage available after the load module has 
been loaded. In a multitasking 
environment, it will be 8K bytes for the 
major task and 8K bytes for each subtask. 
The ISA will include: 

• Dynamic block requirements. These 

lengths can be obtained from the table 
produced by the STORAGE compiler option. 
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Variable data areas, that is, varying- 
length strings and arrays, whose bounds 
or dimensions are not known at compile 
time. The programmer must calculate 
these lengths himself. 



Controlled and based variables, 
lengths should be known to the 
programmer. 



These 



The third area consists of the remainder 
of main storage. It is retained by the 
system and is made available on specific 
main storage requests for overflow from the 
ISA and for I/O requirements, that is, file 
control blocks, buffers, system I/O modules 
and also for PL/I transient library modules 
(that is, storage overflow, program 
initialization, and I/O transmission 
modules) . 

The storage requirements in this third 
area can be calculated only with 
difficulty. The simplest way is to use the 
Storage Management Facilities (SMF) as 
described in the publication OS 
Introduction to determine the total main 
storage requirements for the job. This 
figure is only meaningful if an accurate 
figure for the ISA has been supplied. 

The length of the ISA can greatly affect 
the performance of the program. If it is 
too large there will be wasted storage in 
the ISA which might result in insufficient 
main storage being available for I/O 
requirements and transient library modules 
requirements . 

If it is too small then dynamic main 
storage requirements will be met by 
specific requests to the system (that is, 
from the third area of main storage) 
resulting in slow execution. The 
programmer's total ISA requirements can be 
determined either by calculation or by 
using the REPORT execution-time option. 

This can most easily be done in one of 
two ways: 

1. If sufficient main storage is 
available, specify an ISASIZE larger 
than will be required. The report 
will then give the amount of this ISA 
used and this figure will be the 
optimum ISASIZE. 

2. If there is a shortage of main storage 
specify an ISASIZE of 1, which will 
ensure that the program will run if at 
all possible and the report will still 
give the amount of main storage which 
should be allocated to the ISA. 

Note that for optimum efficiency, the 
ISA should contain all dynamic main storage 
requirements. If however, certain blocks 



are entered only occasionally, cr 
controlled or based variables allocated 
only briefly, these variables could well be 
permitted to remain outside the ISA. So 
long as these allocations dc net clash with 
a larger I/C requirement the program may 
run in a smaller main storage area. 



Execution-Time COUNT Option 



Statement count information can be obtained 
at execution time only if one of the 
compiler options COUNT or FLOW was 
specified at compile time (see "Compiler 
Options" earlier in this chapter.) If FLOW 
but not COUNT was specified at compile 
time, COUNT must be specified at execution 
to obtain count information. If COUNT was 
specified at compile time, count 
information will be produced unless NOCOUNT 
is specified at execution time. 

Count information can be produced only 
when a statement number table exists. If 
COUNT is specified at compile time, a table 
is automatically produced. If only FLOW is 
specified at compile time, and COUNT is 
specified at execution time, then to obtain 
count information, GOSTMT or GONUMBER must 
also be specified at compile time. 

Count output is written en the PLIDUMP 
file, or on the SYsPRINT file if no dump 
file is provided. The output has the 
following format: 



PROCEDURE namel 

FROM TO 

1 20 

21 30 



COUNT 

1 

10 



200 



210 



PROCEDURE name2 

FROM TO 
1 10 



COUNT 
5 



Three such columns are printed per page. 

To draw attention to statements that 
have not been executed, ranges for which 
the count is zero are listed separately 
after the main tables. 

The count tables are printed when the 
program terminates. If a procedure is 
invoked with one of the multitasking 
options, the count table for the invocation 
is printed when the task terminates. 
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I If an invocation is terminated as a 
j result of the termination of another task, 
jits count table cannot be printed, because 
jit is impossible to determine the point at 
(which it terminated. In these 
(circumstances, only the count table for the 
(first task to terminate can be printed. 
(For example, although a STOP statement will 
j cause all tasks to be terminated, only the 
(count table for the task containing the 
(statement will be printed. 



Execution -Time FLOW Option 



name is the name of the 

procedure cr the type of 
the on-unit that contains 
"sn2" if this is different 
from that containing 
"snl" . 

The branches are listed in the order in 
which they occur. The last "n" branch- 
in/branch-out points and the last n m" 
procedures or on-units are listed. If more 
than "m" procedures or on-units are entered 
in the course of "n" branches, changes 
prior tc the last "m" procedures or on- 
units are indicated by printing "UNKNOWN" 
for "naire". 



Flow information can be obtained at 
execution time only if one of the compiler 
options COUNT or FLOW was specified at 
compile time (see "Compiler Options" 
earlier in this chapter.) If FLOW was not 
specified at compile time, it must be 
specified at execution time to obtain flow 
information. If FLOW was specified at 
compile time, flow information will be 
produced unless NOFLOW is specified at 
execution time. 

The format of the execution- time FLOW 
option is the same as that of the compile- 
time FLOW option, that is: 

FLOWt (n,m)] 

If "n" and "m" are not specified at 
execution time, the values taken are as 
follows : 

• If FLOW was specified or defaulted at 
compile time, the values of "n" and "m" 
specified or defaulted at compile time 
are taken. 

• If NOFLOW was specified or defaulted at 
compile time, the IBM default values, 
(25,10), are taken. 

Flow output is written on the SYSPRINT 
file whenever an on-unit with the SNAP 
option is executed. It is also included as 
part of PLIDUMP output if "T" is included 
in the dump options string. 



The format of each line of flow output 



is: 



snl TO sn2 [IN name] 

where snl is the number of the 

statement from which the 
branch was made (the 
branch out point). 

sn2 is the number of the 

statement to which the 
branch was made (the 
branch in point) . 



Compiler Listing 



During compilation, the ccirpiler generates 
a listing, most of which is optional, that 
contains information about the source 
program, the compilation, and the object 
module. It places this listing in the data 
set defined by the DD statement with the 
name. SYSFRINT (usually cutput tc a 
printer) . In a TSO environment, you can 
also request a listing at ycur teririnal 
(using the TERMINAL option). The following 
description of the listing refers tc its 
appearance on a printed page. 

An example of the listing produced for a 
typical PL/ I program is given in appendix 
F. 

Figure 4-7 specifies the components that 
can be included in the compiler listing, 
and the order in which they appear. The 
rest of this section then describes these 
in detail. 

Of course, if compilation terminates 
before reaching a particular stage cf 
processing, the corresponding listings will 
not appear. 

System information will appear before 
and after the listings for each job step if 
these items use the same output class as 
the processing programs. The output class 
for system information is specified in the 
MSGCLASS parameter of the JOB statement. 
The level of information produced is 
specified in the MSGLEVEL parameter. 

The listing comprises a small amount of 
standard information that always appears, 
together with those items of optional 
information specified or supplied by 
default. The listing at the terminal 
contains only the optional information that 
has been requested in the TERMINAL cption. 
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Listings 



| Options required 



Options used for the compilation 
Preprocessor input 
Source program 
Statement nesting level 
Attribute table 
Cross-reference table 
Aggregate length table 
Storage requirements 
Statement offset addresses 
External symbol dictionary 
Static internal storage map 
Object listing 
Messages 



OPTIONS 

MACRO and INSOURCE 

SOURCE 

NEST 

ATTRIBUTES 

XREF 

AGGREGATE 

STORAGE 

SOURCE, OFFSET, NOSTMT 

ESD 

MAP 

LIST 

FLAG 



Figure 4-7. Compiler listings and associated options 



HEADING INFORMATION 



The first page of the listing is identified 
by the name of the compiler, the compiler 
version number, the time compilation 
commenced (if the system has the timer 
feature) , and the date; this page, and 
subsequent pages are numbered. 

The listing either ends with a statement 
that no errors or warning conditions were 
detected during the compilation, cr with 
one or more messages. The format of the 
messages is described under "Messages," 
later in this chapter. If the machine has 
the timer feature, the listing also ends 
with a statement of the CPU time taken for 
the compilation and the elapsed time during 
the compilation; these times will differ 
only in a multiprogramming environment. 

The following paragraphs describe the 
optional parts of the listing in the order 
in which they appear. 



OPTIONS USED FOR THE COMPILATION 

If the option OPTIONS applies, a complete 
list of the options used for the 
compilation, including the default options, 
appears on the first page. 



PREPROCESSOR INPUT 



If both the options MACRO and INSCURCE 
apply, the input to the preprocessor is 
listed, one record per line, each line 



numbered sequentially at the left. 

If the preprocessor detects an error, or 
the possibility of an error, it prints a 
message on the page or pages following the 
input listing. The format cf these 
messages is exactly as described for the 
compiler messages described under 
"Messages," later in this chapter. 



SOURCE FROGRAM 



If the option SOURCE applies, the input to 
the compiler is listed, one record per 
line; if the input records contain printer 
control characters or XSKIP or %PAGE 
statements, the lines will be spaced 
accordingly. 

If the option NUMBER applies, and the 
source program contains line numbers, these 
numbers are printed tc the left cf each 
line. 

If the option STMT applies,, the 
statements in the source program are 
numbered sequentially by the compiler, and 
the number of the first statement in the 
line appears to the left of each line in 
which a statement begins. When an END 
statement closes more than one group or 
block, all the implied END statements are 
included in the count. For example: 
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1 P: 


PROC; 


2 X: 


BEGIN? 


3 


IF A=B 




THEN A=l; 


4 


ELSE DO; 


5 


A=0; 


6 


C=B; 


7 


END X; 


9 


D=E; 


10 


END; 



If the source statements are generated by 
the preprocessor, columns 73-80 contain 
diagnostic information, as shown in Figure 
4-8. 



Column Information 

73-77 Input line number from which 
the source statement is 
generated. This number 
corresponds to the line number 
in the preprocessor input 
listing. 

Two-digit number giving the 
maximum depth of replacement by 
the preprocessor for this line. 
If no replacement occurs, the 
columns are blank. 

80 "E" signifying that an error 

has occurred while replacement 
is being attempted. If no 
error has occurred, the column 
is blank. 

Figure 4-8. Contents of columns 73 to 
80 of source statements 



78,79 



ATTRIBUTE AND CROSS-REFERENCE TABLE 



If the option ATTRIBUTES applies, the 
compiler prints an attribute table 
containing a list of the identifiers in the 
source program together with their declared 
and default attributes. In this context, 
the attributes include any relevant 
options, such as REFER, and also 
descriptive comments, such as: 

/♦STRUCTURE*/ 

If the option XREF applies, the compiler 
prints a cross-reference table containing a 
list of the identifiers in the source 
program together with the nuirbers of the 
statements or lines in which they appear. 
If both ATTRIBUTES and XREF apply, the two 
tables are combined. 



Attribute Table 



If an identifier is declared explicitly, 
the number of the DECLARE statement is 
listed. An undeclared variable is 
indicated by asterisks. The statement 
numbers of statement labels and entry 
labels are also given. 

The attributes INTERNAL and REAL are 
never included; they can be assumed unless 
the respective conflicting attributes, 
EXTERNAL and COMPLEX, appear. 

For a file identifier, the attribute 
FILE always appears, and the attribute 
EXTERNAI appears if it applies; otherwise, 
only explicitly declared attributes are 
listed. 



STATEMENT NESTING LEVEL 



If the option NEST applies, the block level 
and the do-level are printed to the right 
of the statement or line number under the 
headings LEV and NT respectively, for 
example: 



STMT 


LEV 


NT 






1 







A: PROC 


OPTIONS (MAIN) 


2 


1 





B:PROC(L) ; 


3 


2 





DO 


1=1 to 10; 


4 


2 


1 




DO J=l TO 10; 


5 


2 


2 




X(I,J)=N; 


6 


2 


2 




END; 


7 


2 


1 




BEGIN; 


8 


3 


1 




X=Y; 


9 


3 


1 




END; 


10 


2 


1 


END B; 


11 


1 





END A; 



For an array, the dimension attribute is 
printed first; the bounds are printed as in 
the array declaration, but expressions are 
replaced by asterisks and structure levels 
other than base elements have their bounds 
replaced by asterisks. 

For a character string or a bit string, 
the length, preceded by the word BIT or 
CHARACTER, is printed as in the 
declaration, but an expression is replaced 
by an asterisk. 



Cross-reference Table 



If the cross-reference table is combined 
with the attribute table, the numbers of 
the statements or lines in which an 
identifier appears follow the list of 
attributes for the identifier. The number 
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of a statement in which an implicitly- 
pointer qualified based variable appears 
will be included not only in the list of 
statement numbers for that variable, but 
also in the list of statement numbers for 
the pointer associated with it implicitly. 

| If a based variable is referenced 
I without explicit pointer qualification, a 
| reference to the implicit pointer used will 
I be included in the cross-reference listing. 

Note that an END statement that refers 
to a label does not have its statement 
number listed in the entry for the label. 

Identifiers that are initialized during 
execution of prologue code on entry to a 
block will have the PROCEDURE or EEGIN 
statement number included in the list of 
statement numbers. For example, automatic 
variables with the INITIAL attribute in a 
single- block program will have a reference 
to statement number 1 in the cross- 
reference table. 

The order in which the statement numbers 
appear for a particular identifier is 
subject to any reordering of blocks that 
has occurred during compilation. In 
general, the statement numbers for the 
outermost block are given first, followed 
on the next line by the statement numbers 
for the inner blocks. 

| The PL/I text is expanded to a certain 
| extent before the cross-reference list is 
jproduced. Consequently, an identifier 
I within a statement may acquire multiple 
J references to the same statement number, 
j Common examples are the use of do-groups 
jand statements involving aggregates. 



AGGREGATE LENGTH TABLE 



An aggregate length table is obtained by 
using the AGGREGATE option. The table 
shows how each aggregate in the program is 
mapped. It contains the following 
information: 

• The statement number in which the 
aggregate is declared. 

• The name of the aggregate and the 
element within the aggregate. 

• The level number of each item in a 
structure. 

• The number of dimensions in an array. 

• The byte offset of each element from the 
beginning of the aggregate. (The bit 
offset for unaligned bit-string data is 



not given) . 

• The length of each element. 

• The total length of each aggregate, 
structure and sub-structure. 

| If there is padding between twc 

| structure elements, a /+PADDING*/ comment 

j appears , with appropriate diagnostic 

j information. 

The table is completed with the sum of the 
lengths of all aggregates that do not 
contain adjustable elements. 

The statement or line number identifies 
either the DECLARE statement for the 
aggregate, or, for a controlled aggregate, 
an ALLOCATE statement for the aggregate. 
An entry appears for each ALLOCATE 
statement involving a controlled aggregate, 
as such statements can have the effect of 
changing the length of the aggregate during 
execution. Allocation of a based aggregate 
does not have this effect, and only one 
entry, which is that corresponding tc the 
DECLARE statement, appears. 

The length of an aggregate may not be 
known during compilation, either because 
the aggregate contains elements having 
adjustable lengths or dimensions, cr 
because the aggregate is dynamically 
defined. In these cases, the word 
"adjustable" or "defined" appears in the 
"length in bytes" column. 

An entry for a COBOL mapped structure, 
that is, for a structure into which a COBOL 
record is read or from which a COBOL record 
is written, or for a structure passed to or 
from a COBOL program, has the word "COBOL" 
appended. Such an entry will appear only 
if the compiler determines that the COBOL 
and PL/I mapping for the structure is 
different, and creation of a temporary 
structure mapped according tc COBOL rules 
is not suppressed by one of the options 
NOMAP, NCMAPIN, and NOMAPOUT. 

An entry for a FORTRAN mapped array, 
that is, an array passed to or from a 
FORTRAN program, has the word "FORTRAN" 
appended. 

If a COBOL or FORTRAN entry does appear 
it is additional to the entry for the PL/I 
mapped version of the structure. 



STORAGE REQUIREMENTS 



If the option STORAGE applies, the compiler 
lists the following information under the 
heading "storage Requirements" en the page 



Chapter 4: The Compiler 37 



following the end of the aggregate length 
table: 



EXTERNA! SYMBOL DICTIONARY 



• The storage area in bytes for each 
procedure. 

• The storage area in bytes for each begin 
block. 

• The storage area in bytes for each on- 
unit. 

• The length of the program control 
section. The program control section is 
the part of the object module that 
contains the executable part of the 
program. 

• The length of the static internal 
control section. This control section 
contains all storage for variables 
declared STATIC INTERNAL. 



STATEMENT OFFSET ADDRESSES 



If the option OFFSET applies, the compiler 
lists, for each primary entry point, the 
offsets at which statements occur. This 
information is found, under the heading 
"Table of offsets and Statement Numbers," 
following the end of the storage 
reguirements table. 
t+l;unc 

The following method can be used to find 
the statement number that corresponds to an 
offset given in an execution-time error 
message. 

1. From the error message, find the 
offset that is calculated from a 
procedure or ON statement. 

2. In the table of offsets, locate the 
offsets for the named procedure or on- 
unit, and within this section find the 
largest offset that is less than the 
offset given in the error message. 
Note the corresponding statement or 
line number. 



If the option ESD applies, the compiler 
lists the contents of the external symbol 
dictionary (ESD). 

The ESD is a table containing all the 
external symbols that appear in the object 
module. (The machine instructions in the 
Object module are grouped together in what 
are termed con t ro 1 secti ons ; an external 
symbol is a name that can be referred to in 
a control section other than the cue in 
which it is defined.) The contents cf an 
ESD appear under the following headings: 



SYMBOL 



TYPE 



An 8- character field that 
identifies the external 
symbol . 

Two characters from the 
following list to identify 
the type of entry: 

SD Section definition: the 
name of a control section 
within the object mcdule. 

CM Common area: a type of 
control secticn that 
contains no data or 
executable instructions. 

ER External reference: an 
external symbol that is 
not defined in the cbject 
module. 

WX Weak external reference: 
an external symbol that 
is net defined in this 
module and that is not to 
be resolved unless an ER 
entry is encountered for 
the same reference. 

PR Pseudo-register: a field 
in a communications area, 
the task ccniruni cat ions 
area (TCZO, used by the 
compiler and by the 
library subroutines for 
handling files and con- 
trolled variables. 



3. in the source listing, refer to the 
statement or line number. If this is 
not a BEGIN statement, it is the 
statement at which the error occurred. 
If it is a BEGIN statement, locate the 
offsets for the begin block in the table 
of offsets (look for the statement or 
line number) , and find the largest 
offset that is less than the begin block 
offset given in the error message. Note 
the statement or line number, and repeat 
from (3). 



ID 



LD Label definition: the 

name of an entry point to 
the external procedure 
other than that used as 
the name of the program 
control secticn. 

Four-digit hexadecimal number: 
all entries in the ESD, except 
LD-type entries, are numbered 
sequentially, commencing from 
0001. 
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ADDR 



LENGTH - 



Hexadecimal representation of 
the address of the external 
symbol . 

The hexadecimal length in 
bytes of the control section 
(SD # CM, and PR entries only), 



ESD Entries 



STATIC INTERNAL) . This name is the 
first label of the external procedure, 
padded on the left with asterisks to 
seven characters if necessary, and 
extended on the right with the character 
2. 

ER-type entry for IBMBPIRA, the entry 
point of the PL/I resident library 
subroutine that handles program 
initialization and termination. 



The external symbol dictionary always 
starts with the following standard entries; 
the entries for an external procedure with 
the label NAME are shown in Figure 4-9. 

• SD-type entry for PL IS TART . This 

control section transfers control to the 
initialization routine IBMBPIR. When 
initialization is complete, control 
passes to the address stored in the 
control section PLIMAIN. 
(Initialization is required only once 
during the execution of a PL/I program, 
even if it calls another external 
procedure; in such a case, control 
passes directly to the entry point named 
in the CALL statement, and not to the 
address contained in PLIMAIN. ) 



r 

| EXTERNAL 


SYMBOL 


1 

DICTIONARY | 


| SYMBOL 


TYPE 


ID 


ADDR 


LENGTH | 


|PLI START 


3D 


0001 


000000 


000034 | 


|***NAME1 


SD 


0002 


000000 


000100 | 


|***NAME2 


SD 


0003 


000000 


000100 | 


JPLITABS 


WX 


0004 


000000 




j IBMBPIRA 


ER 


0005 


000000 




JIBMBPIRD 


ER 


0006 


000000 




JIBMBPIRC 


ER 


0007 


000000 




| PLICALLA 


LD 




000006 




j PLICALLB 


LD 




00000A 




| PLIMAIN 


SD 


0008 


000000 


000004 | 



Figure 4-9. Standard entries in the 
ESD 



SD-type entry for the program control 
section (the control section that 
contains the executable instructions of 
the object module) . This name is the 
first label of the external procedure, 
padded on the left with asterisks to 
seven characters if necessary, and 
extended on the right with the character 
1. 

SD-type entry for the static internal 
control section (which contains main 
storage for all variables declared 



Other ESD Entries 



The remaining entries in the external 
symbol dictionary vary, but generally 
include the following: 

• SD-type entry for the 4 -byte control 
section PLIMAIN, which contains the 
address of the priirary entry point to 
the external procedure. This control 
section is present only if the procedure 
statement includes the option MAIN. 

• Weak external reference to PLIT^ES, a 
library subroutine that contains the 
standard or locally-defined tab setting 
for stream-oriented output. 

• LD-type entries for all names of entry 
points to the external procedure. 

• A PR-type entry for each block in 
compilation. 

• ER-type entries for all the library 
subroutines and external procedures 
called by the source program. This list 
includes the names of resident library 
subroutines called directly by compiled 
code (first-level subroutines), and the 
names of other resident library 
subroutines that are called by the 
first-level subroutines. 

• CM-type entries for non-string element 
variables declared STATIC EXTERNAL 
without the INITIAL attribute. 

• SD-type entries for all other STATIC 
EXTERNAL variables and fcr external file 
names . 

• PR-type entries for all file names. For 
external file names, the name cf the 
pseudo- register is the same as the file 
name; for internal file names, the 
compiler generates names as for the 
display pseudo-registers. 

• PR-type entries for all controlled 
variables. For external variables, the 
name of the variable is used fcr the 
pseudo-register name; for internal 
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variables, the compiler generates naires. 



a possible error, although the statement 
to which it refers is syntactically 
valid. 



STATIC INTERNAL STORAGE MAP 



If the option MAP applies, the compiler 
generates a listing of the contents of the 
static internal control section; this 
listing is termed the static internal 
storage map . 

The MAP option also produces a Variable 
Storage Map. This map shows how PL/I data 
items are mapped in main storage. It names 
each PL/I identifier, its level, its offset 
from the start of the storage area in both 
decimal and hexadecimal form, its storage 
class, and the name of the PL/I block in 
which it is declared. 



OBJECT LISTING 



An error (E) message describes an error 
detected by the compiler for which the 
compiler has applied a "fix-up" with 
confidence. The resulting program will 
execute and will probably give correct 
results. 



A severe error (S) message specifies an 
error detected by the compiler for which 
the compiler cannot apply a "fix-up" 
with confidence. The resulting program 
will execute but will net give correct 
results. 



An unrecoverable error (U) message 
describes an error that forces 
termination of the compilation. 



If the option LIST applies, the compiler 
generates a listing of the machine 
instructions of the object module, 
including any compiler- generated 
subroutines, in a form similar to IBM 
System/360 assembler language. 

Both the static internal storage map and 
the object listing contain information that 
cannot be fully understood without a 
knowledge of the structure of the object 
module. This is beyond the scope of this 
manual, but a full description of the 
object module, the static internal storage 
map, and the object listing can be found in 
OS PL/I Optimizing Compiler: Execution 
Logic . 



The compiler lists only these messages 
with a severity equal to or greater than 
that specified by the FLAG option, as shown 
in Figure 1-10. 



Type of message 

Informatory 

Warning 

Error 

Severe Error 

Unrecoverable Error 



Option 

FLAG (I ) 
FLAG(W) 
FLAG (E ) 
FLAG(S) 
Always listed 



Figure 4-10. 



Selecting the lowest 
severity of messages to 
be printed, using the 
FLAG option 



MESSAGES 



If the preprocessor or the compiler detects 
an error, or the possibility of an error, 
they generate messages. Messages generated 
by the preprocessor appear in the listing 
immediately after the listing of the 
statements processed by the preprocessor. 
Messages generated by the compiler appear 
at the end of the listing. All messages 
are graded according to their severity, as 
follows: 

• An informatory (I) message calls 
attention to a possible inefficiency in 
the program or gives other information 
generated by the compiler that may be of 
interest to the programmer. 

• A warning (W) message calls attention to 



Each message is identified by an 

8 -character code of the form IELnnnnI, 

where: 

• The first three characters "IEL" 
identify the message as coming from the 
optimizing compiler. 

• The next four characters are a 4 -digit 
message number. 

• The last character "I" is an operating 
system code for the operator indicating 
that the message is for information 
only. 

The text of each message, an 
explanation, and any recommended programmer 
response, are given in the messages 
publication for this compiler. 
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RETURN CODES 



For every compilation job or job step, the 
compiler generates a return code that 
indicates to the operating system the 
degree of success or failure it achieved. 
This code appears in the "end of step" 
message that follows the listing cf the job 
control statements and job scheduler 
messages for each step. The meanings of 
the codes are given in Figure 4-11. 



Meaning 



No error detected; 
compilation completed; 
successful execution 
anticipated. 

Possible error (warning) 
detected; compilation 
completed; successful 
execution probable. 

Error detected; compilation 
completed; successful 
execution probable. 

Severe error detected; 
compilation may have been 
completed; successful 
execution improbable. 

Unrecoverable error 
detected; compilation 
terminated abnormally; 
successful execution 
impossible. 



Figure 4-11. Return codes from 

compilation of a PL/I 
program 



Return 
Code 



0000 



0004 



0008 



0012 



0016 



statement of each external procedure except 
possibly the first. The PROCESS statements 
identify the start of each external 
procedure and allow compiler options to be 
specified individually for each 
compilation. The first procedure iray 
require a PROCESS statement of its own, 
because the options in the PARM parameter 
of the EXEC statement apply to all 
procedures in the batch, and may conflict 
with the requirements of subsequent 
procedures. 

The method of coding a PROCESS statement 
and the options that may be included are ; 
described under "Optional Facilities," 
earlier in this chapter. The options 
specified in a PROCESS statement apply to 
the compilation of the source statements 
between that FRCCESS staterrent and the next 
PROCESS statement. Options other than 
these, either the defaults cr those 
specified in the PARM field, will also 
apply to the compilation of these source 
statements. Two options, the SIZE option 
and the NAME option have a particular 
significance in batched compilations, and 
are discussed below. 



SIZE Option 



In a batched compilation, the SIZE 
specified in the first procedure cf a batch 
(by a PROCESS or EXEC statement, or by 
default) is used throughout. If SIZE is 
specified in subsequent procedures of the 
batch, it is diagnosed and ignored. The 
compiler does not reorganize its storage 
between procedures of a batch. 



NAME Option 



Batched Compilation 



Batched compilation allows the compiler to 
compile more than one external PL/I 
procedure in a single job step. The 
compiler creates an object module for each 
external procedure and stores it 
sequentially either in the data set defined 
by the DD statement with the name SYS PUNCH, 
or. in the data set defined by the DD 
statement with the name SYSLIN. Batched 
compilation can increase compiler 
throughput by reducing operating system and 
compiler initialization overheads. 

To specify batched compilation, include 
a compiler PROCESS statement as the first 



The NAME option specifies that the compiler 
is to place a linkage editor NAME statement 
as the last statement of the object irodule. 
The use of this option in the PARM 
parameter of the EXEC statement, or in a 
PROCESS statement determines hew the object 
modules produced, by a batched compilation 
will be handled by. the linkage editor. 
When the batch of object modules is link- 
edited, the linkage editor combines all the 
object modules between one N3ME statement 
and the preceding NAME statenent into a 
single load module; it takes the name of 
the load module from the NAME statement 
that follows the last object module that is 
| to be included. When combining two object 
| modules into one load module, the NAME 
j option should not be used in the EXEC 
statement. An example of the use of the 
NAME option is given in Figure 4-12. 
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// EXEC PLIXC,PARM.PLI='LIST' 



|* PROCESS NAME ('A'); 

ALPHA: PROC OPTIONS (MAIN) ; 



END ALPHA; 
* PROCESS; 
BETA: PROC; 



JOB CONTROL LANGUAGE FOR EATCHED 
PROCESSING 



The only special consideration relating to 
JCL for batched processing refers to the 
data set defined by the ED statement with 
the name SYSLIN. If you include the option 
OBJECT, ensure that this DD statement 
contains the parameter DISP= (MOD, KEEP) or 
DISP= (MOD, PASS) . (The IBM-supplied 
cataloged procedures specify 
DISP= (MOD, PASS) . ) If you do not specify 
DISP=MOD, successive object modules will 
overwrite the preceding modules. 



END BETA; 
* PROCESS NAMECB'); 
GAMMA: PROC; 



END GAMMA; 



Figure 4-12. 



Use of the NAME option 
in batched compilation 



Examples of Batched Compilations 



If the external procedures are components 
of a language program and need to be 
executed together, they can be link-edited 
together and executed in subsequent job 
steps. Cataloged procedure PLIXCG can be 
used, as shown in Figure 4-13. 



Compilation of the PL/I procedures 
ALPHA, BETA, and GAMMA, would result in the 
following object modules and NAME 
statements: 

Object module for ALPHA 

NAME A (R) 
Object module for BETA 
Object module for GAMMA 

NAME B (R) 

From this sequence of object modules and 
control statements, the linkage editor 
would produce two load modules, one named A 
containing the object module for the 
external PL/ I procedure ALPHA, and the 
other named B containing the object modules 
for the external PL/ I procedures BETA and 
GAMMA. 



//OPT4#13 JOB 
//STEPl EXEC PLIXCG 
//PLI.SYSIN DD * 

First PL/I source module 

* PROCESS; 

Second PL/I source module 

* PROCESS; 

Third PL/I source module 
/* 
//GO. SYS IN DD * 

Data processed by combined 

PL/ I modules 



/* 



Figure 4-13. Example of batched 

compilation, including 
execution 



You should not specify the option NAME 
if you intend to process the object modules 
with the loader. The loader processes all 
object modules into a single load module; 
if there is more than one name, the loader 
recognizes the first one only and ignores 
the others. 



Return Codes in Batched Compilation 



The return code generated by a batched 
compilation is the highest code that would 
be returned if the procedures were compiled 
separately. 



//OPT4#14 JOB 
//STEPl EXEC PLIXCL, 
//PARM.FLI= , NAME(•PROGl , ) , , 
//PARM.LKED=LIST 
//PLI.SYSIN DD * 

First PL/I source program 

* PROCESS NAME ( • PROG2 '• ) ; 

Second PL /I source program 

* PROCESS NAME ( ' PR0G3 ' ) ; 

Third PL/ I source program 
/* 

//LKED.SYSLMOD DD DSN=PUBPGM, 
//DISP=OLD 



Figure 4-14. 



Example of batched 
compilation, excluding 
execution 
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If the external procedures are 
independent programs to be invoked 
individually from a load module library, 
cataloged procedure PLIXCL can be used. 
For example, a job that contains three 
compile-and-link-edit operations can be run 
as a single batched compilation, as shown 
in Figure 4-14. 



One of these programs, such as PR0G2 , 
can be invoked from the load module library 
as follows: 

//OPTEX JOB 

//JOBLIB DD DSNAME=PUBPGM,DISP=SHR 

//J2 EXEC PGM=PR0G2 

//SYS IN DD * 

Data processed by program PR0G2 
/* 



Compile-time Processing (preprocessing) 



The preprocessing facilities of the 
compiler are described in the language 
reference manual for this compiler. You 
can include in a PL/I program statements 
that, when executed by the preprocessor 
stage of the compiler, modify the source 
program or cause additional source 
statements to be included from a library. 
The following discussion supplements the 
information contained in the language 
reference manual by providing some 
illustrations of the use of the 
preprocessor and explaining how to 
establish and use source statement 
libraries. 



INVOKING THE PREPROCESSOR 



sequence of instructions that have 
previously been defined. 

The format of the preprocessor output is 
given in Figure 4-15. 



Column 1 



Columns 2-72 



Columns 73-80 



Column 81 
Columns 8 2,83 



Printer control character, 
if any, transferred from 
the position specified in 
the MARGINS option. 

Source program. If the 
original source program 
used more than 71 columns, 
then additional lines are 
included for any lines that 
need continuation. If the 
original source program 
used less than 71 columns, 
then extra blanks are added 
on the right. 

Sequence number, 
right- aligned. If either 
SEQUENCE or NUMBER apply, 
this is taken from the 
sequence number field. 
Otherwise, it is a 
preprocessor generated 
number, in the range 1 
through 99999. This 
sequence number will be 
used in the listing 
produced by the INSOURCE 
and SOURCE options, and in 
any preprocessor diagnostic 
messages. 

blank 

Two-digit number giving the 
maximum depth of 
replacement by the 
preprocessor for this line. 
If no replacement occurs, 
the columns are blank. 



The preprocessor stage of the compiler is 
executed if you specify the compiler option 
MACRO. The compiler and the preprocessor 
use the data set defined by the DD 
statement with the name SYSUTl during 
processing. They also use this data set to 
store the preprocessed source program until 
compilation begins. The IBM- supplied 
cataloged procedures for compilation all 
include a DD statement with the name 
SYSUTl. 

The term MACRO owes its origin to the 
similarity of some applications of the 
preprocessor to the macro language 
available with such processors as the IBM 
System/36 Assembler, such a macro 
language allows you to write a single 
instruction in a program to represent a 



Column 8 4 "E" signifying that an 

error has occurred while 
replacement is being 
attempted. If no error has 
occurred, the column is 
blank. 

Figure 4-15. Format of the 

preprocessor output 



Three other compiler options, MDECK, 
INSOURCE, and SYNTAX, are meaningful only 
when you also specify the MACRO option. 
All are described earlier in this chapter. 

A simple example of the use of the 
preprocessor to produce a source deck for a 
procedure SUBFUN is shown in Figure 4-16; 
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//OPT 4 #16 JOB 

//STEPl EXEC PLIXC, PARM.PLI=' MACRO r NOSYNT AX ,MDECK' 

//PLI. SYS PUNCH DD DSNAME=NEWLIB (SUBPROC) ,DISP= (NEW,CATLG) ,UNIT=2311, 
// VOL=SER=D186,SPACE=(CYL, (1,1,1)) 

//PLI. SYS IN DD * 
SUBFUN: PROC (CITY) ; 

DCL IN FILE RECORD, 
1 DATA, 

2 NAME CHAR (10) , 
2 POP FIXED (7) , 
CITY CHAR (10) ; 

%DCL USE CHAR; 

%USE='SUB' /* FOR FUNCTION, SUBSTITUTE %USE='FUN' */ ; 

NEXT: READ FILE(IN) INTO(DATA); 

IF NAME=CITY THEN DO; 

%IF USE='FUN' 55THEN %GOTO Ll; 

NO=POP; END; 

%GO TO L2; 
%L1 : ; RETURN ( POP ) ; END ; 
%L2: ; ELSE GO TO NEXT; 

END SUBFUN; 
/* 

Figure 4-16. Using the preprocessor to create a member of a source program library 



according to the value assigned to the 
preprocessor variable USE, the source 
statements will represent either a 
subroutine or a function. 



THE % INCLUDE STATEMENT 



The language reference manual for this 
compiler describes how to use the %INCLUDE 
statement to incorporate source statements 
from a library into a PL/ I program. (A 
library is a type of data set that can be 
used for the storage of other data sets, 
termed members » ) A set of source 
statements that you may wish to insert into 
a PL/I program by means of a ^INCLUDE 
statement must exist as a data set (member) 
within a library. Creating a library and 
placing members in this library, are 
described in Chapter 10. 

The %INCLUDE statement includes one or 
more pairs of identifiers. Each pair of 
identifiers specifies the name of a DD 
statement that defines a library and, in 
parentheses, the name of a member of the 
library. For example, the statement: 

| SlINCLUDE DDK INVERT) , DD 2 (LOOPX) ; 

specifies that the source statements in 
member INVERT of the library defined by the 
DD statement with the name DDl, and those 
in member LOOPX of the library defined by 



the DD statement with the name ED2, are to 
be inserted consecutively into the source 
program generated by the preprocessor. The 
compilation job step must include 
appropriate DD statements. 

If you omit the ddname from any pair of 
identifiers in a ^INCLUDE statement, the 
preprocessor assumes the ddname SYSLIB. In 
such a case, you must include a ED 
statement with the name SYSLIB. (The IBM- 
supplied cataloged procedures do net 
include a DD statement with this name in 
the compilation procedure step.) 

The preprocessor will not recognize a 
PROCESS statement in a source statement 
module included by a %INCLUDE statement. 
The presence of such a PROCESS statement 
will result in an error in the compilation. 

The use of a %INCLUDE statement to 
| include the source statements for SUBPROC 
in the procedure TEST is shown in Figure 
4-17. The library NEWLIB is defined in the 
DD statement with the qualified name 
PL I. SYSLIB, which is added to the 
statements of the cataloged procedure 
PLIXCLG for this job. Since the source 
statement library is defined by a DE 
statement with the name SYSLIB, the 
^INCLUDE statement need not include a 
ddname. 

It is not necessary to invoke the 
preprocessor if your source program, and 
any text to be included, contains no 
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//OPT4#17 JOB 

//STEP1 EXEC PLIXCLG^ARM.PLI^MACRO, OBJECT' 
//PLI.SYSLIB DD DSNAME=NEWLIB ,DISP=OLD 
//PLI.SYSIN DD * 

TEST: PROC OPTIONS (MAIN) ; 

DCL NAME CHAR (10) , 
NO FIXED (7) ; 

ON ENDFILE(SYSIN) GO TO FINISH; 

AGAIN: GET FILE (SYSIN) LIST (NAME) ; 
CALL SUBFUN(NAME) ; 
PUT DATA (NAME , NO) ; 
GO TO AGAIN; 
%INCLUDE SUBPROC; 
FINISH: END TEST; 
/* 

//GO. IN DD DSNAME=POPLIST,DlSP=OLD 
//GO. SYSIN DD * 
'ABERDEEN* 
•DONCASTER' 
/* 

Figure 4-17. Including source statements from a library 



preprocessor statements other than 
%INCLUDE. Under these circumstances, 
faster inclusion of text can be obtained by 
specifying the INCLUDE compiler option. 



Dynamic Invocation of the Compiler 



You can invoke the optimizing compiler from 
an assembler language program by using one 
of the macro instructions ATTACH, CALL, 
LINK, or XCTL. The following information 
supplements the description of these macro 
instructions given in the manual OS/360 
Supervisor and Data Management Macro 
Instructions . 

To invoke the compiler specify IELOAA as 
the entry point name. 

You can pass three address parameters to 
the compiler: 

1. The address of a compiler option list. 



indicate the end of the list. 

Note: If you want to pass parameters in an 
XCTL macro instruction, you must use the 
execute (E) form of the iracrc instruction. 
Remember also that the XCTL macro 
instruction indicates to the control 
program that the load module containing the 
XCTL macro instruction is completed. Thus 
the parameters must be established in a 
portion of main storage outside the load 
module containing the XCTL nacro 
instruction, in case the load module is 
deleted before the compiler can use the 
parameters. 

The format of the three parameters for 
all the macro instructions is described 
below. 



2. The address of a list of dd names for 
the data sets used by the compiler. 

3. The address of a page number that is 
to be used for the first page of the 
compiler listing on SYSPRINT. 

These addresses must be in adjacent 
fullwords, aligned on a fullword boundary. 
Register 1 must point to the first address 
in the list, and the first (left-hand) bit 
of the last address must be set to 1, to 



OPTION LIST 



The option list must begin on a halfword 
boundary. The first two bytes contain a 
binary count of the number of bytes in the 
list (excluding the count field). The 
remainder of the list can comprise any of 
the compiler option keywords, separated by 
one or more blanks, a comma, or both of 
these. 
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Entry 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

Figure 4-18, 



DDNAME LIST 



Standard ddname 

SYSLIN 

not applicable 

not applicable 

SYSLIB 

SYSIN 

SY SPRINT 

SYS PUNCH 

SYSUT1 

not applicable 

not applicable 

not applicable 

not applicable 

not applicable 

SYSCIN 

The sequence of entries 
in the ddnanie list 



The ddname list must begin on a half word 
boundary. The first two bytes contain a 
binary count of the number of bytes in the 



list (excluding the count field). Each 
entry in the list must occupy an 8-byte 
field; the sequence of entries is given in 
Figure 4-18. 

If a ddname is shorter than eight bytes, 
fill the field with blanks on the right. 
If you omit an entry, fill its field with 
binary zeros; however you may omit entries 
at the end of the list entirely. 



PAGE NUN.BER 



The page number is contained in a 6-byte 
field beginning on a halfwcrd boundary. 
The first halfword must contain the binary 
value 4 (the length of the remainder of the 
field) . The last four bytes contain the 
page number in binary fcrm. 

The compiler will add 1 to the last page 
number used in the compiler listing and put 
this value in the page-number field before 
returning control to the invoking routine. 
Thus, if the compiler is reirvcked, page 
numbering will te continuous. 
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Chapter 5: The Linkage Editor and the Loader 



This chapter describes two processing 
programs of the operating system, the 
linkage editor and the loader . It explains 
the basic differences between them, 
describes the processing done by them, the 
JCL required to invoke them and, for the 
linkage editor, the additional processing 
it can do. Both processing programs are 
fully described in OS ; Linkage Editor and 
Loader . 

The object module produced by the 
compiler from a PL/ I program always 
requires further processing before it can 
be executed. This further processing, the 
resolution of external references inserted 
by the compiler, is performed either by the 
linkage editor or by the loader, both of 
which convert an object module into an 
executable program, which in the case of 
the linkage editor, is termed a load 
module . 

The linkage editor and the loader 
require the same type of input, perform the 
same basic processing, and produce a 
similar type of output. The basic 
differences between the two programs lie in 
the subsequent form and handling of this 
output . 



Basic Differences 



The linkage editor converts an object 
module into a load module, and stores it in 
a program library in auxiliary storage. 
The load module becomes a permanent member 
of that library and can be retrieved at any 
time for execution in either the job that 
created it, or in any other job. 

The loader, on the other hand, processes 
the object module, loads the processed 
output directly into main storage, and 
executes it immediately. The loader is 
essentially a one-shot program checkout 
facility; once the load module has been 
executed, it cannot be used again without 
reinvoking the loader. To keep a load 
module for later execution, or to provide 
an overlay structure, you must use the 
linkage editor. 

When using the linkage editor, three job 
steps are required — compilation, link 
editing, and execution. When using the 
loader, only two job steps are required — 
compilation and execution. 



Choice of Program 



If your installation includes both 
programs, the choice of program will depend 
on whether or not you want to retain a 
permanent copy of the lead ncdule, and on 
whether you want to use one of the 
facilities provided only by the linkage 
editor. All object modules acceptable to 
the linkage editor are acceptable tc the 
loader; all load modules produced by the 
linkage editor, except these produced with 
the NE (not editable) attribute 1 , are also 
acceptable to the loader. The differences 
between the two programs are summarized 
below. 



Linkage Editor 



The linkage editor converts an object 
module into a load module and stores it 
in a partitioned data set (program 
library) in auxiliary storage. 

The linkage editor can produce cne or 
more load modules in a single step (for 
example, output from batch compilation). 

The linkage editor can accept input from 
other sources as well as from its 
primary input source and from the 
automatic call library (S'XSLIB). 

The linkage editor can provide an 
overlay structure for a program. 



Loader 



The loader converts an object module 
into an executable program in main 
storage, and executes it immediately. 

The loader can produce only one load 
module in a single job step no matter 
how many object modules are produced 
(for example, the output from a batch 
compilation) . 



x The NE attribute is given tc a lead module 
that has no external symbol dictionary 
(ESD) ; a load module without an ESD cannot 
be processed again, either by the linkage 
editor or by the loader. 
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The loader can accept input from its 
primary input source and from the 
automatic call library (SYSLIB). 



• END instruction 



Text 



Performance Considerations 



If you use the loader, you will gain the 
advantage of a considerable saving in both 
time and auxiliary storage when running 
your PL/I program. Although the execution 
time will be unchanged, both the scheduling 
time and the processing time will be 
reduced, and much less auxiliary storage 
will be needed. These savings are achieved 
as follows: 

Scheduling Time : Scheduling time for the 
loader is much less than that for link 
editing and execution because the loader 
needs only one job step. 

Processing Time : The time taken to process 
an object module by the loader is 
approximately half that taken by the 
linkage editor to process the same module. 
This is achieved by the elimination of 
certain input /output operations required by 
the linkage editor, and by a reduction in 
module access time by the use of chained 
scheduling and improved buffering in the 
loader program. 

Auxiliary storage : The amount of auxiliary 
storage required by the loader when your 
job is compiled, loaded, and executed as a 
single job step, is much less than that 
required by the linkage editor because two 
of the standard data sets used by the 
linkage editor are not needed. If the 
loader input is to consist of existing load 
modules the auxiliary storage required for 
these can be reduced by storing them with 
unresolved external references. These 
external references are resolved fcy the 
loader. 



The text of an object or load module 
consists of the machine instructions that 
represent the PL/I statements of the source 
program. These instructions are grcuped 
together in what are termed control 
sections; a control section is the smallest 
group of machine instructions that can be 
processed by the linkage editor- An object 
module produced by the optimizing compiler 
includes the following control sections: 

• Program control section: contains the 
executable instructions of the object 
module. 

• Static internal control section: 
contains storage for all variables 
declared STATIC INTERNAL and for 
constants and static system blocks. 

• Control sections termed c ommon areas one 
common area is created fcr each EXTERNAL 
file name and for each non- string 
element variable declared STATIC 
EXTERNAL without the INITIAL attribute. 

• PLISTART: execution of a PL/I program 
always starts with this control section, 
which passes control to the appropriate 
initialization subroutine? when 
initialization is complete, control 
passes to the address stored in the 
control section PLIMAIN. 

• Control sections for all FL/I library 
subroutines to be included with the 
program. 



External Symbol Dictionary 



Module Structure 

Object and load modules have very similar 
structures; they differ only in that a load 
module that has been processed by the 
linkage editor contains certain descriptive 
information required by the operating 
system; in particular, the module is marked 
as "executable" or "not executable". A 
module comprises the following information: 

• Text (TXT) 

• External symbol dictionary (ESD) 

• Relocation dictionary (RLD) 



The external symbol dictionary (ESD) is a 
table containing all the external symbols 
that appear in the object module. An 
external symbol is a name that can be 
referred to in a control section other than 
the one in which it is defined. 

The names of the control sections are 
themselves external symbols, as are the 
names of variables declared with the 
EXTERNAL attribute and entry names in the 
external procedure of a PL/I program. 
References to external symbols defined 
elsewhere are also considered to be 
external symbols; they are known as 
external references . Such external 
references in an object module always 
include the names of the subroutines from 
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END Instruction 



Column 



33 



34 to 41 



44 to 47 



Information 

The number of IDR entries 
that follow. This is 
always "1" for the 
optimizing compiler. 

The program number of the 
compiler. (5734-PL1 for 
the optimizing compiler. ) 

The release number of the 
compiler. For example, 
'0102' indicates Release 
1.2. 



The date in day-month-year 
form. 



48 to 53 
Figure 5-1. The CSECT IDR information 



either the OS PL/ I Resident Library or the 
OS PL/I Transient Library that will be 
required for execution. They may also 
include calls to your own subroutines that 
are not part of the PL/I subroutine 
library, nor already included within the 
object module. The linkage editor or 
loader locates all the subroutines referred 
to, and includes them in the load module, 
or executable program respectively. 



Relocation Dictionary 



At execution time, the machine instructions 
in a load module Use the following two 
methods of addressing locations in main 
storage: 

1. Names used only within a control 
section have addresses relative to the 
starting point of the control section. 

2. Other names (external names) have 
absolute addresses so that any control 
section can refer to them. 

The relocation dictionary (RLD) contains 
information that enables absolute addresses 
to be assigned to locations within the load 
module when it is loaded into main storage 
for. execution. These addresses cannot be 
determined earlier because the starting 
address is not known until the module is 
loaded. The relocation dictionaries from 
all the input modules are combined into a 
single relocation dictionary when a load 
module is produced. 



This specifies the compiler-generated 
control section PLISTART as the entry point 
for the object module. It also contains 
"CSECT IDR" information fcr processing by 
the linkage editor. The CSECT IDR 
information is given in Figure 5-1. 



Linkage Editor 



The linkage editor is an operating system 
processing program that produces lead 
modules. It always stores the load modules 
in a library, from which the jcb scheduler 
can call them for execution. 

The input to the linkage editor can 
include object modules, load ircdules, and 
control statements that specify how the 
input is to be processed. The output from 
the linkage editor comprises one or more 
load modules. 

In addition to its primary function of 
converting object modules into load 
modules, the linkage editor can alsc be 
used to: 

• Combine previously link- edited load 
modules. 

• Modify existing load modules. 

• Construct an overlay structure. 

A load module constructed as an overlay 
structure can be executed in an area of 
main storage that is not large enough to 
contain the entire module at one tine. The 
linkage editor divides the load module into 
segments that can be leaded and executed in 
turn. 



LINKAGE EDITOR PROCESSING 



A PL/ I program, compiled by the optimizing 
compiler, cannot .be executed until the 
appropriate library subroutines have been 
included. These subroutines are included 
in two ways : 

1. Ey inclusion in the load module during 
link editing. 

2. By dynamic call during executicn. 

The first method is used for mest of the 
PL/I resident library subroutines; the 
following paragraphs describe how the 
linkage editor locates them. The second is 
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SYSLIN 

(primary input) 
r n 

I I 

| PL/I object | 
j module | 



j PL/I library j 
| (SYSl.PLIBASE) | 
I I 

l_. - J 

SYSLIB 
(call library) 



■>l 



linkage 
editor 



->l 



Figure 5-2. Basic linkage editor processing 



SYSLMOD (load 
module library) 
r 1 

I I 

■> | load module | 

I I 

I I 



used for the PL/I transient library 
subroutines, for example those concerned 
with input and output (including those used 
for opening and closing files), and those 
that generate execution-time messages. 

In basic processing, as shown in Figure 
5-2, the linkage editor accepts from its 
primary input source a data set defined by 
the DD statement with the name SYSLIN. For 
a PL/I program, this input is the object 
module produced by the compiler. The 
linkage editor uses the external symbol 
dictionary in this object module to 
determine whether the module includes any 
external references for which there are no 
corresponding external symbols in the 
module: it attempts to resolve such 
references by a method termed a ut erratic 
library call . 

External symbol resolution by automatic 
library call involves a search of the data 
set defined by the DD statement with the 
name SYSLIB; for a PL/I program, this will 
be the PL/I resident library. The linkage 
editor locates the subroutines in which the 
external symbols are defined (if such 
subroutines exist) , and includes there in 
the load module. 

The linkage editor always places its 
output (that is, the load module) in the 
data set defined by the DD statement with 
the name SYSLMOD. 

Any linkage editor processing additional 
to the basic processing described above 
must be specified by linkage editor control 
statements placed in the primary input. 



These control statements are described in 
"Additional Processing," later in this 
chapter. 



Main Storage Requirements 



The F-level linkage editor has three 
different versions requiring differing 
amounts of main storage: 44K„ 88K, and 
128K bytes. The F-level linkage editor is 
described in the linkage editor and loader 
publication. 



Job Control Language for the Linkage 
Editor 



Although you will probably use cataloged 
procedures rather than supply all the job 
control language (JCL) required for a job 
step that invokes the linkage editor, you 
should be familiar with these JCL 
statements so that you can make the best 
use of the linkage editor and, if 
necessary, override the statements of the 
cataloged procedures. 

The IBM-supplied cataloged procedures 
that include a link- edit procedure step 
are: 
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PLIXCL Compile and link edit 

PLIXCLG Compile, link edit, and execute 

PLIXLG Link edit and execute 

The following paragraphs describe the 
essential JCL statements for link editing. 
The IBM-supplied cataloged procedures are 
described in Chapter 11 and include 
examples of these statements. 



EXEC STATEMENT 



The name of the linkage editor is of the 
form IEWLFxxx, where "xxx" indicates the 
amount of main storage required fcr its 
execution, as shown in Figure 5-3. 



xxx | 

1 


Amount of 
main storaqe 


440 | 
880 | 
128 | 


44K 
88K 
128K 



Figure 5-3. Main storage requirements 
for linkage editor 
IEWLFxxx 



The aliases IEWL or LINKEDIT are often 
used for the linkage editor and normally 
refer to the version at your installation 
with the largest design level. Ycu should 
find out what versions are available at 
your installation. 

The basic EXEC statement is: 



A fifth data set, defined by a EE 
statement with the name SYSLIB, is 
necessary if you want tc use automatic 
library call. The five data set names, 
together with other characteristics cf the 
data sets, are shown in Figure 5-4. 



Primary Input (SYSLIN) 



Primary input to the linkage editor must be 
a standard data set defined by a ED 
statement with the name SYSLIN; this data 
set must have consecutive organization. 
The input must comprise cne cr ircre object 
modules and/or linkage editor control 
statements; a load module car.nct be part cf 
the primary input, although it can be 
introduced by the control statement 
INCLUDE. For a PL/I program, the primary 
input is usually a data set containing an 
object module produced by the compiler. 
This data set may be en magnetic tape or en 
a direct-access device, or you can include 
it in the input job stream. In all cases, 
the input must be in the form of 80-byte F- 
format records. 

The IBM-supplied cataloged procedure 
PLIXLG includes the DD statement: 

//SYSLIN DD DDNAME=SYSIN 

This statement specifies that the 
primary input data set may be defined in a 
DD statement with the name SYSIN. If you 
use this cataloged procedure, specify this 
DD statement by using the qualified ddname 
IKED. SYSIN. For example, tc link edit and 
execute an object module placed in the 
input stream, you can use the following 
statements : 



//LEGC 

//STEP1 
//IKED. SYSIN 



JOB 

EXEC PLIXLG 

DD * 



//stepname EXEC PGM=IEWL 

By using the PARM parameter of the EXEC 
statement, you can select one or more of 
the optional facilities provided by the 
linkage editor; these facilities are 
described in "Optional Facilities," later 
in this chapter. 



DD STATEMENTS FOR THE STANDARD DATA 
SETS 



The linkage editor always requires four 
standard data sets. You must define these 
data sets in DD statements with the ddnames 
SYSLIN, SYSLMOD, SYSUTl , and SYSPRINT. 



(insert here the object module tc be 
link edited and executed) 



/* 



If object modules with identically named 
control sections appear in the primary 
input, the linkage editor processes enly 
the first appearance of that control 
section. 

You can include load modules cr object 
modules from one or more libraries in the 
primary input by using a linkage editor 
INCLUDE statement as described in 
"Additional Processing," later in this 
chapter. 
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ddname 



Contents 



| Possible device classes 1 



SYSLIN 

SYSLMOD 
SYSUTl 
SYSPRINT 
SYSLIB 



Primary input data, normally 
the compiler output 

Load module 

Temporary workspace 

Listing, including messages 

Automatic call library 
(normally the PL/I 
resident library) 



UNIT=SYSSQ or input jcb stream 
(specified by DD *) 

UNIT=SYSDA 

UNIT=SYSDA 

UNIT=SYSSQ (or SYSOUT=) 

UNIT=SYSDA 



^SYSSQ Magnetic tape or direct-access device 
SYSDA Direct access device 



Figure 5-4. Linkage editor standard data sets 



Output (SYSLMOD) 



Output (that is, one or more load modules) 
from the linkage editor is always stored in 
a data set defined by the DD statement with 
the name SYSLMOD, unless you specify 
otherwise. This data set is usually called 
a library; libraries are fully described in 
Chapter 10. 

The IBM-supplied cataloged procedures 
include the following DD statement: 

//SYSLMOD DD DSNAME=SSGOSET (GO) , 

// UNIT=SYSDA, 

// DISP= (MOD, PASS) , 

// SPACE=(1024, (50,20,1) ,RLSE) ) 

This statement defines a temporary 
library named SSGCSET and assigns the 
member name GO to the load module produced 
by the linkage editor. To retain the lead 
module after execution of the job, replace 
this DD statement with one that defines a 
permanent library. For example, assume 
that you have a permanent library called 
USLIB on 2311 disk pack serial number 371; 
to name the load module MCDl and place it 
in this library, code: 

//LK ED. SYSLMOD DD DSNAME=USLIB (MODI) , 
// UNIT=2311,VCL=SER=371,DISP=CLD 

The size of a load module must not 
exceed 512K bytes for programs executed 
under MFT; a much larger load module is 
allowed for MVT. The SPACE parameter in 
the DD statement with the name SYSLMOD used 
in the IBM-supplied cataloged procedures 
allows for an initial allocation of 50K 



bytes and, if necessary, 15 further 
allocations of 20K bytes (a tctal cf 350K 
bytes); this should suffice for most 
applications. 



Temporary Workspace (SYSUTl) 



The linkage editor requires a data set for 
use as temporary workspace. It is defined 
by a DD statement with the raire SYSUTl. 
This data set must be on a direct-access 
device. The following statenent contains 
the essential parameters: 

//SYSUTl DD UNIT=SYSDA, 
// SPACE=(1024, (200,20)) 

You should normally never need to alter 
the DD statement with the nane SYSUTl in an 
IBM-supplied cataloged procedure, except to 
increase the SPACE allccaticr when 
processing very large programs. 

If your installation supports dedicated 
workfiles, these can be used tc prcvide 
temporary workspace for the link-edit job 
step, as described in Chapter 11. 



Automatic Call library (SYSLIB) 



Unless you specify otherwise, the linkage 
editor will always attempt to resolve 
external references by automatic library 
call (see "Linkage Editor Processing," 
earlier in this chapter) . Tc enable it to 
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do this, you must define the data set or 
data sets to be searched in a DD statement 
with the name SYSLIB. (To define second 
and subsequent data sets, include 
additional, unnamed, DD statements 
immediately after the DD statement SYSLIB; 
the data sets so defined will be treated as 
a single continuous data set for the 
duration of the job step. ) 

For a PL/I program, the DD statement 
SYSLIB will normally define the PL/I 
resident library. The subroutines of the 
resident library are stored in two data 
sets, SYSl.PLIBASE (the base library) and 
SYS1.PLITASK (the multitasking library). 
The base library contains all the resident 
library subroutines required by a non- 
multitasking program. The multitasking 
library contains subroutines that are 
peculiar to multitasking, together with 
multitasking variants of some of the base 
library subroutines. 

For link editing a non- mult it asking 
program, specify only the base library in 
the SYSLIB DD statement. The following DD 
statement will usually suffice: 

//SYSLIB DD DSN=SYS1.PLIBASE,DISP=0LD 

For link editing a multitasking program, 
specify both the multitasking library and 
the base library. When attempting to 
resolve an external reference, the linkage 
editor will first search the multitasking 
library; if it cannot find the required 
subroutine, it will then search the base 
library. To ensure that the search is 
carried out in the correct sequence, the DD 
statements defining the two sections of the 
library must be in the correct sequence: 
multitasking library first, base library 
second. The following DD statements will 
usually suffice: 

//SYSLIB DD DSNAME=SYS1.PLITASK,DISP=0LD 
// DD DSNAME=SYS1.PLIBASE,DISP=0LD 



Listing (SYSPRINT) 



The linkage editor generates a listing that 
includes reference tables relating to the 
load modules that it produces and also, 
when necessary, messages. The information 
that may appear is described under "Listing 
Produced by the Linkage Editor, " later in 
this chapter. 

You must define the data set on which 
you wish the linkage editor to store its 
listing in a DD statement with the name 
SYSPRINT. This data set must have 
consecutive organization. Although the 
listing is usually printed, it can be 



stored on any magnetic-tape cr direct- 
access device. For printed output, the 
following statement will suffice: 

//SYSPRINT DD SYSOUT=A 



EXAMPLE OF LINKAGE EDITOR JCL 



A typical sequence of job control 
statements for link editing an object 
module is shown in Figure 5-5. The DD 
statement SYSLIN indicates that the cbject 
module will follow initediately in the input 
stream; for example, it might be an cbject 
deck created by invoking the optimizing 
compiler with the DECK option, as described 
in Chapter 4. The DD statement with the 
name SYSIMOD specifies that the linkage 
editor is to name the load module LKEX,; and 
that it is to place it in a rew library 
naired MODLIB; the keyword NEW in the DjSP 
parameter indicates to the operating systeir 
that this DD statement specifies the 
creation of a library. 



Optional Facilities 



The linkage editor provides a number of 
optional facilities that are selected by 
including the appropriate keywords from the 
following list in the PARM parameter of the 
EXEC statement that invokes it: 

LIST 

MAP or XREF 

LET or XCAL 

NCAL 

SIZE 

Code PARK= followed by the list of 
options, separating the opticns with commas 
and enclosing the list within single 
quotation marks, for exairple: 

//STEPA EXEC PGM=IEWL,PARM=* LIST, MAP 1 

If you are using a cataloged procedure, 
you must include the FARM parameter in the 
EXEC statement that invokes the procedure 
and qualify the keyword PARM with the name 
of the procedure step that invokes the 
linkage editor, for example: 

//STEPA EXEC PLIXCLG^ARM.LKED^LIS^XREF* 

The linkage editor opticns are of two 
types : 

1. Simple keywords, for example, LIST, 

that specifies a facility. LET, LIST, 
. MAP, NCAL, XCAL, and XREF are of this 
type. 
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//LINK JOB 

//STEP1 EXEC PGM=IEWL 

//SYSLMOD DD DSNAME=MODLIB(LKEX) ,UNIT=2311 ,V0L=SER=D186 

// SPACE=(CYL, (10, 10,1)) f DISP=(NEW f KEEP) 

//SYSUTl DD UNIT=SYSDA,SPACE= (1024, (200,20)) 

//SYSPRINT DD SYSOUT=A 

//SY3LIB DD DSNAME=SYS1.PL1BASE,DISP=0LD 

//SYSLIN DD * 



(insert here the object module to be link-edited) 



/* 

Figure 5-5. Typical job control statements for link editing a PL/I prcgrarr 



2. Keywords that permit you to assign a 
value to a function (for exairple, 
SIZE=10K) . 



library call. However, the lead ircdule is 
marked "executable" provided that there are 
no errors. 



The linkage editor options are described 
in the following sections, in alphabetic 
order. 



LET Option 



The LET option specifies that the linkage 
editor is to mark the load module as 
"executable" even if slight errors or 
abnormal conditions have been found during 
link editing provided these do not exceed 
severity 2. 



You can use the NCAL opticn to conserve 
auxiliary storage in private libraries, 
since, by preventing the resolution cf 
external references during link editing, 
you can store load modules without the 
relevant library subroutines; the DD 
statement with the name SYSLIE is net 
required. Before executing these lead 
modules, you must link edit them again to 
resolve the external references, but the 
load module created need exist only while 
it is being executed. You can use this 
technique to combine separately compiled 
PL/I procedures into a single lead ircdule. 



LIST Option 



SIZE Option 



The LIST option specifies that all linkage 
editor control statements processed should 
be listed in the data set defined by the DD 
statement with the name 'SYSPRINT. 



MAP Option 



The MAP option specifies that the linkage 
editor is to produce a map of the load 
module showing the relative locations and 
lengths of all control sections in the load 
module. 



NCAL Option 



The NCAL option specifies that no external 
references are to be resolved by automatic 



The SIZE option specifies the amount of 
main storage, in bytes, to be allocated to 
the linkage editor. The f orrrat of the SI ZE 
option is : 

SIZE=(m[,n]) 

where "m" is the amount cf rrain storage 
in bytes or K bytes (where 
K=102<D to be allocated to the 
linkage editor; it must 
include "n" and it must be 
greater than "n." 

and "n" which is optional, is the 
amount of main storage (in 
bytes or K bytes) tc be 
allocated to the load module 
buffer. 

Figure 5-6 gives values fcr "ir" and "n" 
for the three versions of the F-level 
linkage editor. 
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r 1 

Version I m (minimum) | n | m-n 
j j (Min) (Max) j (Min) 



44K 

88K 

128K 



44K j 6K 100K | 38K 
88K | 6K 100K j 4UK 
128K j 6K 100K | 66K 



L J 



Figure 5-6. Coding the SIZE option 



If you specify SIZE incorrectly, or if 
you omit it r default values set at system 
generation are used. If you specify SIZE 
greater than the region or partition size, 
the maximum amount of main storage will be 
used. 



default. The optional components of the 
listing and the corresponding linkage 
editor options are as shown in Figure 5-7, 



[ Options Required ! 
LIST 

MAP or XREF 

XREF 

L J 

Figure 5-7. Linkage editor listings 
and associated cpticns 



Listings 

Control statements 
processed by the 
linkage editor 

Map of the load module 

Cross-reference table 



XCAL Option 



The XCAL option specifies that the linkage 
editor will mark the load module as 
"executable" even if slight errors or 
abnormal conditions, including improper 
branches between control sections, have 
been found during link editing. XCAL, 
which implies LET, applies only to an 
overlay structure. 



The first page of the listing is 
identified by the linkage editor version 
and level number followed by a list of the 
linkage editor options used. 

The following paragraphs describe the 
optional components of the listing in the 
order in which they appear. 

An example of the listing produced for a 
typical PL/ 1 program is given in Appendix 

F. 



XREF Option 



The XREF option specifies that the linkage 
editor is to print a map of the load module 
and a cross-reference list of all the 
external references in each control 
section. XREF implies MAP. 



Listing Produced by the Linkage Editor 



The linkage editor generates a listing, 
most of which is optional, that contains 
information about the link- editing process 
and the load module that it produces. It 
places this listing in the data set defined 
by the DD statement with the name SYSPRINT 
(usually output to a printer) . The 
following description of the listing refers 
to its appearance on a printed page. 

The listing comprises a small amount of 
standard information that always appears, 
together with those items of optional 
information specified in the PARM parameter 
of the EXEC statement that invokes the 
linkage editor, or that are applied by 



Diagnostic Messages and Control 
Statements 

The linkage editor generates messages, 
describing errors or conditions, detected 
during link editing, that may lead tc 
error. These messages are listed 
immediately after the heading information 
on page 1 of the linkage editor listing. 
They are listed again at the end of the 
linkage editor listing under the heading 
"Diagnostic Message Directory" which is 
described later in this chapter. 

If you have specified the option LIST, 
the names of all control statements 
processed by the linkage editor are listed 
immediately preceding the messages, and are 
identified fcy the 7-character code IEW0O0O. 

Each message is identified by a similar 
7-character code of the form IEWnnnx, 
where: 

• The first three characters "IEW" 
identify the message as ccming frcm the 
linkage editor. 

• The next three characters are a 3-digit 
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message number. 

The last character "x" is a severity 
code. The possible severity codes and 
their meanings are given in Figure 5-8. 



Severity 
Code 



Meaning 



A condition that will not cause an 
error during execution. The load 
module is marked as "executable". 

1 A condition that may cause an error 
during execution. The load module 
is marked as "executable". 

2 An error that could make execution 
impossible. The load module is 
marked as "not executable " unless 
you have specified the option LET. 

3 An error that will make execution 
impossible. The load module is 
marked as "not executable". 

4 An error that makes recovery 
impossible. Linkage editor 
processing is terminated, and no 
output other than messages is 
produced. 



Figure 5-8. 



Diagnostic message 
severity codes 



At the end of the listing, immediately 
preceding the "Diagnostic Message 
Directory" (described later in this 
chapter), the linkage editor places a 
statement of the disposition of the load 
module. The disposition statements, with 
one exception, are self-explanatory; the 
exception is: 

****modulename DOES NOT EXIST BUT HAS 
BEEN ADDED TO DATA SET 



completed, the linkage editor lists in full 
all the messages whose nuirbers appear in 
the preceding list. The text of each 
message, an explanation, and any 
recommended programmer response, are given 
in the linkage editor and leader 
publication. 

The warning message IEW04 61, together 
with a return code of 0001, frequently 
appears in the linkage editor listing for a 
PL/I program. It refers to external 
references that have not been resolved 
because NCAL is specified. The references 
occur in PL/I library subroutines that are 
link edited with your program as a result 
of automatic library call. Scire library 
subroutines may, in turn, call other 
library subroutines. For these secondary 
subroutines that are required, the compiler 
generates another external symbol 
dictionary containing alternative names for 
the subroutines. These new references can 
be resolved, and the required subroutines 
placed in the new load module. If the 
secondary subroutines in turn call ether 
subroutines, the process is repeated. 



MODULE MAP 



The linkage editor listing includes a 
module map only if you specify the options 
MAP or XREF. The map lists all the control 
sections in the load module and all the 
entry point names in each control section. 
The control sections are listed in order of 
appearance in the load module; alongside 
each control section name is its address 
relative to the start of the load module 
(address 0) and its length in bytes. The 
entry points within the load module appear 
on the printed listing below and to the 
right of the control sections in which they 
are defined; each entry point name is 
accompanied by its address relative to the 
start of the load module. 



This appears when the NAME statement has 
been used to add a new module to the data 
set defined by the DD statement with the 
name SYSLMOD. The use of the NAME 
statement is described under "Module Name," 
later in this chapter. If you name a new 
module by including its name in the DSNAME 
parameter of the DD statement with the name 
SYSLMOD, the linkage editor assumes that 
you want to replace an existing module 
(even if the data set is new) . 



DIAGNOSTIC MESSAGE DIRECTORY 



When processing of a load module has been 



Each control section that is included by 
automatic library call is indicated by an 
asterisk. For an overlay structure, the 
control sections are arranged by segment in 
the order in which they are specified. 

After the control sections, the rrcdule 
map lists the pseudo-registers established 
by the compiler. Pseudo-registers are 
fields in a communications area, the task 
communications area (TCA) , used by PL/l 
library subroutines and compiled code 
during execution of a PL/I program. The 
main storage occupied by the TCA is not 
allocated until the start of execution of a 
PL/ I program; it does not form part of the 
load module. The addresses given in the 
list of pseu do- registers are relative to 
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Return Code Meaning 

0000 No messages issued; link 
editing completed without 
error; successful execution 
anticipated. 

0004 Warning messages only 
issued; link editing 
completed; successful 
execution probable. 

0008 Error messages only issued; 
link editing completed; 
execution may fail. 

0012 Severe error messages 

issued; link editing may 
have been completed, but 
with errors; successful 
execution improbable. 

0016 Unrecoverable error message 
issued; link editing 
terminated abnormally; 
successful execution 
impossible. 

Figure 5-9. Return codes from the 
linkage editor 



the start of the TCA. 

At the end of the module map, the 
linkage editor supplies the following 
information: 

• The total length of the pseudo- 
registers . 

• The relative address of the instruction 
with which execution of the load module 
will commence (ENTRY ADDRESS). 

• The total length of the load module. 
For an overlay structure, the length is 
that of the longest path. 

All the addresses and lengths given in 
the module map and associated information 
are in hexadecimal. 



module, the symbol to which the reference 
refers, and the name of the control section 
in which the symbol is defined. 

For an overlay structure, a cross- 
reference table is provided for each 
segment. It includes the number of the 
segment in which each syirbcl is defined. 

Unresolved symbols are identified in the 
cross-reference table by the entries 
$UNRESOLVED or $NEVER-CAIL. An unresolved 
weak external reference (WXTRN) is 
identified by the entry $UNRESOLVID (W) . 



RETURN CODE 



For every linkage editor job or job step, 
the linkage editor generates a return code 
that indicates to the operating system the 
degree of success or failure it achieved. 
This code appears in the "end of step" 
message and is derived by multiplying the 
highest severity code (see "Diagnostic 
Messages and control Statements," earlier 
in this chapter) by four, as shown in 
Figure 5-9. 

The return code 0004 almost invariably 
appears after a PL/I program has been link 
edited because some external references 
will not have been resolved. (Refer to 
"Diagnostic Message Directory," earlier in 
this chapter.) 



Additional Processing 



Basic processing by the linkage editcr 
produces a single load module from the data 
that it reads from its primary input, but 
it has several other facilities that you 
can call upon by using linkage editcr 
control statements. The use of those 
statements of particular relevance tc a 
PL/ I program is described below. All the 
linkage editor control statements are fully 
described in the linkage editor and loader 
publication. 



CROSS-REFERENCE TABLE 



FORMAT OF CONTROL STATEMENTS 



The linkage editor listing includes a 
"Cross-reference Table" only if you specify 
the option XREF. This option produces a 
listing that comprises all the information 
described under "Module Map," above, 
together with a cross-reference table of 
external references. The table gives the 
location of each reference within the load 



A linkage editor control statement is an 
80-byte record that contains two fields. 
The operation field specifies the operation 
required of the linkage editcr; it irust be 
preceded and followed by at least one blank 
character. The operand field names the 
control sections, data sets, or modules 
that are to be processed, and it may 
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contain symbols to indicate the manner of 
processing; the field consists of one or 
more parameters separated by commas. Some 
control statements may have multiple 
operand fields separated by commas. 

The position of a control statement in 
the linkage editor input depends on its 
function . 

In the following descriptions of the 
control statements, items within trackets 
[] are optional. 



MODULE NAME 



the linkage editor ignores it. The 
statement must follow immediately after the 
last object module that will form part of 
the load module it names (or after the 
INCLUDE control statement that specifies 
the last object module). 



Alternative Names 



You can use the ALIAS statement to give a 
load module an alternative name; a lead 
module can have as many as sixteen aliases 
in addition to the name giver to it in a DD 
statement with the name SYSLMOD, or by a 
NAME statement. 



A load module must have a name so that the 
linkage editor and the operating system can 
identify it. A name comprises up to eight 
characters, the first of which must be 
alphabetic. 

You can name a load module in cne of two 
ways: 

1. If you are producing a single load 
module from a single link-edit job 
step, it is sufficient to include its 
name as a member name in the DSNAME 
parameter of the DD statement with the 
name SYSLMOD. 

2. If you are producing two or more load 
modules from a single link- edit job 
step, you will need to use the NAME 
statement. (The optimizing compiler 
can supply the NAME statements when 
you use batch compilation as described 
in Chapter H. ) 

The format of the NAME statement is: 

NAME nameE (R) ] 

| where "name" is any name of up to eight 
characters; the first character must be 
alphabetic. The NAME statement serves the 
following functions: 

• It identifies a load module. The name 
specified will be given to the load 
module. "(R)", if present, specifies 
that the load module is to replace an 
existing load module of the same name in 
the data set defined by the DD statement 
with the name SYSLMOD. 

• It acts as a delimiter between input for 
different load modules in one link- edit 
step . 

The NAME statement must appear in the 
primary input to the linkage editor (the 
standard data set defined by the DD 
statement SYSLIN); if it appears elsewhere. 



The format of the ALIAS statement is: 

ALIAS name 

where "name" is any name of up to eight 
characters; the first character must be 
alphabetic. You can include more than one 
name in an ALIAS statement, separating the 
names by commas,, for example: 

ALIAS FEE, FIE, FOE, FUM 

An ALIAS statement can be placed before, 
between, or after object modules and 
control statements that are being processed 
to form a load module, but it must precede 
the NAME statement that specifies the 
primary name of the load module. 

To execute a load module, you can 
include an alias instead of the primary 
name in the PGM parameter of an EXEC 
statement. 

Aliases can be used for external entry 
points in a PL/I procedure. Hence a CALL 
statement or a function reference to any of 
the external entry names will cause the 
linkage editor to include the module 
containing the alias entry names without 
the need to use the INCLUDE statement for 
this module. 



ADDITIONAL INPUT SOURCES 



The linkage editor can accept input from 
sources other than the primary input 
defined in the DD statement with the name 
SYSLIN. For example,, automatic library 
call enables the linkage editor tc include 
modules from a data set (a library) defined 
by the DD statement with the name SYSLIB. 
You can name these additional input sources 
by means of the INCLUDE statement, and you 
can direct the automatic library call 
mechanism to alternative libraries by means 
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of the LIBRARY statement. 



LIBRARY Statement 



INCLUDE Statement 



The INCLUDE statement causes the linkage 
editor to process the module or modules 
indicated. After the included modules have 
been processed, the linkage editor 
continues with the next item in the priirary 
input. If an included sequential data set 
also contains an INCLUDE statement, that 
statement is processed as if it were the 
last item in the data set, as shown in 
Figure 5-10. 



The basic function of the LIER£RY statement 
is to name call libraries in addition to 
those named in the DD statement SYSLIB. 
The format of the LIEPARY statement is : 

LIBBARY ddname(membername) 

where "ddname" is the name cf a CE 
statement that defines the additional call 
library, and "member name" is the naire of 
the module to be examined by the automatic 
call mechanism. More ^than ere module can 
be specified; separate the module names 
with commas. 



OVERLAY STRUCTURES 



Primary Input Sequential 
Data Set Data Set 



Library 
Member 



| end 
| INCLUDE 




end 

INCLUDE 


j end 




not 

processed 

end end 


Figure 5- 


10. 


Processing of additional 



data sources 



The format of the INCLUDE statement is: 

INCLUDE ddname [ (membername) ] 

where "ddname" is the name of a DD 
statement that defines either a sequential 
data set or a library that contains the 
modules and control statements to be 
processed. If the DD statement defines a 
library, replace "membername" with the 
names of the modules to be processed, 
separated by commas. You can specify more 
than one ddname , each of which may be 
followed by any number of member names in a 
single INCLUDE statement. For example: 

INCLUDE D1(MEM1,MEM2) ,D2 (MODA,MODE) 

specifies the inclusion of the members MEMl 
and MEM2 from the library defined by the DD 
statement with the name Dl # and the members 
MODA and MODB from the library defined by 
the DD statement with the name D2 . 



A load module constructed as an overlay 
structure can be executed in an area of 
main storage that is net large enough to 
contain the entire module at one time. The 
linkage editor divides the load module into 
segments that can be loaded and executed in 
turn. To construct an overlay structure, 
you must use linkage editor control 
statements to specify the relationship 
between the segments. One segment, termed 
the root segment must remain in main 
storage throughout the execution of the 
program. 

In an overlay environment the addressing 
of a static external structure element, 
array, or string may be incorrect if used 
in a data-directed I/O statenent cr CHECK 
statement. This error will arise if the 
control section containing the syirbcl table 
of the identifier, and the corresponding 
static internal control section are not in 
the same overlay segment. This is because 
the symbol table contains the address of a 
locator that is in static internal storage. 
The difficulty can be avoided by ensuring 
that the procedure in the root segment 
contains a reference tc the identifier in a 
data-directed I/O or CHECK context. The 
statement containing the identifier need 
not be executed; its presence ensures that 
the symbol table for the identifier 
addresses the locator in the static 
internal control section of the rcct 
segment. 

| The descriptor for a controlled external 
| aggregate with fixed extents is stored in 
| the static internal control section of the 
| procedure that allocates it. This prevents 
| references to the external variable being 
| made in other procedures that overlay the 
j segment in which it was allocated. A 
j controlled external variable must be 
j allocated in one of two ways: 
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PROC OPTIONS (MAIN) 
CALL B; 
CALL F; 
END A; 

PROC ; 
CALL C; 

END B; 



r 



r 

|D; 



PROC; 
CALL D; 
CALL E; 
END C; 



PROC ; 



j END D; 



IE: PROC; 



Procedure A 



Procedure B 



Procedure C 



Procedure F 



Procedure D 



| END E; | 

L . „_J 

r t 

|F: PROC; | 

I • I 

I • I 

| END F; | 

L J 

Figure 5-11. Overlay structure and its tree 



Procedure E 



1. The variable can be allocated in the 
root phase. A convenient technique to 
use would be to have a subroutine, 
containing the ALLOCATE statement, 
which could be called from any 
segment. 



2. The variable can be allocated with 
adjustable extents, so that the 
descriptor will be copied into the 
controlled storage area when 
allocation takes place. Note that 
this method uses more storage. 



Design of the Overlay Structure 



Eefore preparing the linkage editor control 
statements, you must design the overlay 
structure for your program. A tree is a 
graphic representation of an overlay 
structure that shows which segments cccupy 
main storage at different times. The 
design cf trees is discussed in the linkage 
editor and loader publication,, but for the 
purposes of this chapter. Figure 5-11 
contains a simple example. The program 
comprises six procedures: A, B, c, D, E„ 
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//OPT5#12 JOB 

//STEPl EXEC PLIXCLG, 

PARM.LKED='OVLY' 
//PLI. SYSIN DD * 

(insert here source statements for 
procedure A) 

* PROCESS; 

(insert here source statements for 
procedure B) 

* PROCESS; 

(insert here source statements for 
procedure C) 

* PROCESS; 

(insert here source statements for 
procedure D) 

* PROCESS; 

(insert here source statements for 
procedure E) 

* PROCESS; 

(insert here source statements for 
procedure F) 

/* 

//LKED. SYSIN DD * 

OVERLAY X 

INSERT ******Bl,******Cl 

OVERLAY Y 

INSERT ******D1 

OVERLAY Y 

INSERT ******E1 

OVERLAY X 

INSERT ******F1 
/* 



storage; thus the lines representing 
procedures D and E start from the node X. 

The degree of segmentation that can be 
achieved can be clearly seen frcir the 
figure. since procedure A must always be 
present, it must be included in the root 
segment. Procedures F, D and E can 
usefully be placed in individual segirents, 
as can procedures B and C be placed 
together; there is nothing tc be gained by 
separating procedures B and c, since they 
must be present together at seme tine 
during execution. 



Control statements 



Two linkage editor control statements, 
OVERLAY and INSERT, ccntrcl the 
relationship of the segments in the overlay 
structure. The OVERLAY statement specifies 
the start of a segment and the INSERT 
statement specifies the positions of 
control sections in a segment. You must 
include the attribute CVLY in the PSRM 
parameter of the EXEC statement that 
invokes the linkage editor, otherwise the 
linkage editor will ignore the control 
statements. 

The format of the OVERLAP statement is : 

OVERLAY symbol 

where "symbol" is the node at which the 
segment starts (for example, X in Figure 
5-11). You must specify the start of every 
segment, except the root segment, in an 
OVERLAY statement. 

The format of the INSERT statement is: 

INSERT control-section-name 



Figure 5-12. Creating and executing 

the overlay structure of 
Figure 5-11 



and F. Procedure B calls procedure C 
which, in turn, calls procedures D and E. 
(Only procedure A requires the option 
MAIN. ) 

The main procedure (A) must be in main 
storage throughout the execution of the 
program. since the execution of procedure 
B will be completed before procedure F is 
called, the two procedures can occupy the 
same storage; this is depicted by the lines 
representing the two procedures in Figure 
51-11 starting from the common point (node) 
X. Procedure B must remain in storage 
while procedures C, D, and E are executed, 
but procedures D and E can occupy the same 



where "control-secti 
the control section 
derivative of the pr 
found in the linkage 
be placed in the seg 
control section can 
the names with comma 
statements that name 
in the root segment 
OVERLAY statement. 



cn-narre" is the name of 
(that is, the 
ccedure name that is 

editor map) that is to 
irent. Were than one 
te specified, separate 
s. The INSERT 

the control sections 
must precede the first 



Creating an Ov erlay Structure 

The most efficient method of defining an 
overlay structure, and the simplest for a 
PL/ I program, is to group all the OVERLAY 
and INSERT statements together and place 
them in the linkage editor input (SYSLIN) 
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after the object modules that fonr the 
program. The linkage editor initially 
places all these object modules in the root 
segment, and then moves those control 
sections that are referred to in INSERT 
statements into other segments. 

This method has the advantage that you 
can use batched compilation to process all 
the procedures in one job step and place 
the object modules in a temporary data set; 
this data set must have consecutive 
organization. You can then place the 
linkage editor control statements in the 
input stream, concatenating them with the 
data set that contains the object modules. 
(Do not use the NAME compiler option to 
name the object modules; if you do, the 
NAME statements inserted by the compiler 
will cause the linkage editor to attempt to 
create separate load modules rather than a 
single overlay structure.) 

The use of the IBM-supplied cataloged 
procedure PLIXCLG to create and execute the 
overlay structure of Figure 5-11, is shown 
in Figure 5-12. 

An alternative approach instead of 
batched compilation is to compile the 
procedures independently and store them as 
object modules in a private library. You 
can then use an INCLUDE statement to place 
them in the input to the linkage editor 
(SYSLIN) . 

If an INSERT statement contains the name 
of an external procedure, the linkage 
editor will move only the related program 
control section that has the same name. 
All other control sections established by 
the compiler, and all the PL/I library 
subroutines, will remain in the root 
segment. 

It is important that the PL/I library 
subroutines £>e in the root segment, since 
the optimizing compiler does not support 
exclusive calls (calls between segments 
that do not lie in the same path) . For 
example, in Figure 5-11, procedures in the 
segment containing D could call procedures 
in the segments containing A, B, C, and D, 
but not in the segments containing E or F. 
Procedures in the segments containing B or 
c could call procedures in the segments 
containing A, B, C, D, and E, but not in 
the segment containing F. A procedure in 
the segment containing B may not call a 
procedure in the segment containing A if 
this latter procedure calls a procedure in 
the segment containing F. 

However, certain library subroutines may 
not be required by all segments, in which 
case you can move them into a lower 
segment. To do this, compile the 
procedures using the compiler option ESD, 



and examine the resulting external symbol 
dictionary. For example, if in Figure 5-11 
a library subroutine is called only by the 
segment containing E, you can ircve it into 
that segment by placing an INSERT 
statement, specifying the subroutine name, 
immediately after the statement INSERT 

Similarly, you can move ccntrcl sections 
from the root segment to lower segments. 
For example, to move the static internal 
control section for procedure F into the 
segment containing F, place the statement 
INSERT ******F2 after the statement INSERT 
******F1. Values assigned tc static data 
items are net retained when a segment is 
overlaid. Do not move static data from the 
root segment unless it comprises only: 

• values set by the INITIAL attribute and 
then unchanged (that is, read-only 
data ) . 

• Values that need net be retained between 
different loadings of the segment. 

Care must be taken to ensure that the 
static external control sections for all 
the PL/I files used in an overlay program 
are placed in the root segment. If this is 
not dene, failures may occur when the ERROR 
condition is raised and the PL/I error 
routines attempt to close the files. In 
particular, the static external ccntrol 
section for SYSFRINT must always be placed 
in the root segment. 

| when using the COUNT option, ensure that 
jail procedures for which count information 
| is reguired have their static internal 
J control sections in the root segment, or 
| the count information will be rendered 
invalid. 



LINK EDITING FETCHABLE LCAD MODULES 



The PL/I FETCH and RELEASE statements 
permit the dynamic loading of separate load 
modules which can be subseguently invoked 
from the PL/I object program. 

Fetchable (or dynamically-loaded) 
modules should be link-edited intc a load 
module library which is subsequently made 
available for the job step by means cf a 
JOBLIB or STEPLIB DD statement. 

The step which link-edits a fetchable 
load module into a library requires the 
following linkage editor control 
statements: 

• An ENTRY statement to define the entry- 
point into the PL/I program. 
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Control Present in 
Section 

PLI START All programs 

IBMBJWTl Programs that use the WAIT 
statement 

IBMTJWTl Multitasking programs that use 
the WAIT statement 

IBMBTOC1 Programs that use the 

COMPLETION built in function or 
pseudo variable 

IBMTTOCl Multitasking programs that use 
the COMPLETION built-in 
function or pseud ovari able. 

IBMBTPRl Programs that use the PRIORITY 
pseudo variable 

IBMTTPRl Multitasking programs that use 
the PRIORITY pseudovariable. 

IBMBEFLl Programs compiled with the FLOW 
or COUNT options. 

Figure 5-13. control sections to be 
deleted for optimum 
space-saving 



is net specified in the DSN parameter in 
the SYS1N0D DD statement used to define 
the load module library. 

• Optionally, for optimum space saving, 
REPLACE statements to delete the control 
sections shown in Figure 5-13, if they 
are present in the object module. 

The name or any alias by which the 
fetchable load module is identified in the 
load module library must appear in a FETCH 
or RELEASE statement within the scope of 
the invoking procedure. 

COBOI or FORTRAN modules cannot be 
loaded dynamically by the PL/I FETCH 
statement. 

The job control statements and the 
linkage editor statements to link-edit a 
fetchable load module into a library called 
PRVLIB are given in Figure 5-14. The 
cataloged procedure PLIXCL is used tc 
illustrate these statements ty sharing a 
job that includes both the compilation and 
the link- editing of the fetchable PL/I 
module. 



Combining PL/ I M odules from the 
Optimizing and Checkout Comp ilers 



//FETCH JOB 
//STP EXEC PLIXCL 
//PLI.SYSIN DD * 



PL/I source( fetchable) 



/* 

//LKED . SYSLMOD DD DSN=PRVLIB, . . . 

//LKED.SYSLIN DD DDNAME=SYSIN 

// DD DSN=SSLOADSET,DISP= (OLD, DELETE) 

//LKED.SYSIN DD * 

ENTRY procedure -name 

REPLACE PLI START 

REPLACE IBMBJWTl 

REPLACE IBMBTOCl 

REPLACE IBMBTPRl 

NAME FETCH1 
/* 



Figure 5-14. 



Example of link- editing 
a fetchable load module 



A NAME statement to define the name used 
for the fetchable load module. This 
statement is required if the compiler 
option NAME is not used and if the name 



When a program is to consist of PL/I 
modules compiled by the optimizing and 
checkout compilers, the following points 
should be considered before link-editing 
the modules into a single load module: 

• The modules compiled by the optimizing 
compiler should be link-edited tc form a 
load module. 

• The linkage editor option NCAL must be 
specified for this link-editing 
operation. 

• The load module containing the modules 
compiled by the optimizing compiler can 
now be link-edited with the link-edit 
stubs produced by the checkout ccmpiler. 

This method ensures that the 
initialization routine for a program 
compiled by the optimizing ccmpiler will 
not be included in the final load module 
and that the initialization routine for a 
program compiled by the checkout compiler 
is used when the program is executed. 

Both the space occupied by the final 
load module and its speed of execution are 
affected by the SYSLIB data set specified 
for use by the linkage editor. Two data 
sets, SYS1.PLICMIX and SYSl.PLlBASE are 
available. Use SYSl.PLICMIX to obtain a 
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smaller load module at the expense of 
execution time; use SYSl.PLIBASE to save 
execution time at the expense of space. 



Loader 



The loader is an operating system 
processing program that produces and 
executes load modules. It always stores 
the load modules directly in main storage 
where they are executed immediately. 

The input to the loader can include 
single object modules or load modules, 
several object modules or load modules, or 
a mixture of both. The output from the 
loader always comprises an executable 
program that is loaded into main storage 
from where it will be executed. 

Unlike the linkage editor you cannot use 
any control statements with the loader. If 
any linkage editor control statements are 
used, they will be ignored, and their 
presence in the input stream will not be 
treated as an error. Your job will 
continue to be processed, a message will be 
generated and, if you have included a DD 
statement with the name SYSLOUT, this 
message and the name of the contrcl 
statement will be printed on your listing. 

The loader compensates for the absence 
of the facilities provided by control 
statements by allowing the concatenation of 
both object and load modules in the data 
set defined by the DD statement with the 
name SYSLIN, and by allowing an entry point 
to be specified by means of the EP option, 
as described in "Optional Facilities," 
later in this chapter. 



LOADER PROCESSING 



A PL/I program cannot be executed until the 
appropriate PL/I library subroutines have 
been included. All library subroutines are 
included during loading. In basic 
processing, as shown in Figure 5-15, the 
loader accepts data from its primary input 
source, a data set defined by the DD 
statement with the name SYSLIN. For a PL/ I 
program, this data is the object module 
produced by the compiler. The loader uses 
the external symbol dictionary in this 
object module to determine whether the 
module includes any external references for 
which there are no corresponding external 
symbols in the module: it attempts to 
resolve such references by a method termed 
automatic library call as described in 
"Linkage Editor processing," earlier in 



this chapter. 

The loader locates the subroutines in 
which the external symbols axe defined (if 
such subroutines exist) and includes them 
in the load module. If all external 
references are resolved satisfactorily the 
load module is executed. 

The loader will always search the link- 
pack area before searching the PL/I 
resident library, as shown ir Figure 5-16. 
The link-pack area is an area of main 
storage in which frequently used lead 
modules are stored permanently. If there 
is more than one copy of an object ircdule 
in the data set defined by the ED statement 
with the name SYSLIN, the leader will load 
the first and ignore the rest. 



Main Storage Requirements 



The minimum main storage requirements for 
the loader are shown in Figure 5-17. 

This amounts to at least 17K bytes for 
the loader and its associated routines and 
data areas plus the main storage required 
for the program that is to be executed. If 
the loader program and the data management 
access routines were stored in the link- 
pack area, the amount of irain storage 
required would be 3K bytes for the loader 
data area plus that required by the prograir 
that is to be executed. 



Job Control Language for the Loader 



Although you will probably use cataloged 
procedures rather than supply all the job 
control language (JCL) required for a job 
step that invokes the loader, you should be 
familiar with these JCL statements so that 
you can make the best use of the loader 
and, if necessary, override statements of 
the cataloged procedures. 



The IBM- supplied cataloged procedures 
that include a loader procedure step are as 
follows : 

• PLIXCG Compile, load- and- execute 

• PLIXG Load- and- execute 

The following paragraphs describe the 
essential JCL statements for the loader. 
The IBM-supplied cataloged procedures are 
described in Chapter 11 and include 
examples of these statements. 
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SYS LIN 
(primary input) 

r i 

I I 

| PL/I object A j 

j and/or B| 

jload modules C| 



SYSLIB 
(call library) 
r ~i 

I I 

| PL/I resident D| 
j library E| 
| (SYSl.PLIBASE) FJ 
I G| 

I I 



">l 



loader 




Figure 5-15. Basic loader processing 



SYSLIN 
(primary input) 

r i 

I I 

j PL/I object A j 

j and/or load B| 

jmodules C| 



loader 



SYSLIB r 

(call library) | 

r n | 

I I I 

j PL/I resident DJ j 

jlibrary E| J 

j (SYSl.PLIBASE) F| 

I I 

Figure 5-16. Loader processing, link-pack area and SYSLIB resolution 
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Storage required for: 


|Aircunt (min) 




| in bytes 


Loader program 


| 10K 


Data management access 


| UK 


routines 




Buffers and tables used by 


| 3K 


leader 




PL/I program to be executed 


| variable 



l J 

Figure 5-17. Main storage requirements 
for the loader 



EXEC STATEMENT 



with the name SYSLIN. Three ether standard 
data sets are optional and if you use them 
you must define them in DD statements with 
the names SYSICUT, SYSPRINT, and SYSLIB. 
The four data sets, their names,, and other 
characteristics of the data sets, are shown 
in Figure 5-18. 

The data sets defined by the DD 
statements with the names SYSLIN, SYSLIB, 
and SYSICUT are those specified at system 
generation for your installatien. Other 
ddnames may have been specified at your 
installation; if they have, your JCL 
statements must use them in place of those 
given above, in a similar manner the IBM- 
supplied cataloged procedures PLIXCG and 
PLIXG use names as shown above; ycur 
systems programmer will have to modify 
these procedures if the names at your 
installation are different. 



The name of the loader is IEWLDRGC. It 
also has the alias LOADER, which is used in 
the IBM-supplied cataloged procedures, and 
will be used to refer to the loader program 
in the rest of this chapter. The basic 
EXEC statement is : 

//stepname EXEC PGM= LOADER 

By using the PARM parameter of the EXEC 
statement, you can select one or more of 
the optional facilities provided by the 
loader; these are described under "Optional 
Facilities," later in this chapter. 



DD STATEMENTS FOR THE STANDARD DATA 
SETS 



The loader always requires one standard 
data set; that defined by the DD statement 



Primary Input (SYSLIN) 



Primary input to the loader must be a 
standard data set defined by a DD statement 
with the name SYSLIN; this data set irust 
have consecutive organizaticn. The input 
can comprise one or more object modules, 
one or more load modules, or a mixture of 
object modules and load modules. 

For a PL/I program the primary input is 
usually a data set containing an object 
module produced by the compiler. This data 
set may be on magnetic tape cr en a direct- 
access device, or you can include it in the 
input job stream. In all cases the input 
must be in the form of 80- byte F-format 
records. 

The IBM-supplied cataloged procedure 



r ~ ~~ 

| ddname 


Contents of Data Set | 


Possible Device Classes 1 


| SYSLIN 


Primary input (normally the output from the | 
compiler) j 


SYSSQ or the input job 
stream (specified by DD *) 


| SYSLOUT 


Loader messages and module map listing | 


SYSSQ, SYSDA, or SYSOUT=A 


| SY3PRINT 


PL/I execution -time messages and problem | 
output listing j 


SYSSQ, SYSDA, or SYSOUT=A 


| SYSLIB 


Automatic call library | 


SYSDA 


I 1 SYSSQ 
| SYSDA 
| SYSOUT=A 


Magnetic tape or direct-access device 

Direct-access device 

Normal printed output class for system output 





Figure 5-18. Loader standard data sets 
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PLIXCG includes the DD statement: 

//SYSLIN ED DSN=SSL0ADSET,DISP= (OLD , DELETE) 

This statement specifies that the data 
set SSLOADSET is temporary. If ycu want to 
modify this statement you must refer to it 
by the qualified ddname GO. SYSLIN. 

The IBM-supplied cataloged procedure 
PLIXG does not include a DD statement for 
the input data set; you must always supply 
one, specifying the characteristics of your 
input data set using the qualified ddnaire 
GO. SYSLIN. 



Automatic Call Library (SYSLIB) 



Unless you specify otherwise, the loader 
will normally attempt to resolve external 
references by automatic library call. The 
automatic call library (SYSLIB) , and how to 
specify it, is described in the linkage 
editor section earlier in this chapter. 



Listing (SYSLOUT) 



The loader generates a listing that 
includes a module map (if you have 
specified the MAP option) and, if errors 
have been detected during processing, 
messages referring to these. The 
information that may appear is described in 
"Listing Produced by the Loader," later in 
this chapter. 

You must define the data set in which 
you want this listing to be stored by a DD 
statement with the name SYSLOUT and it must 
have consecutive organization. Although 
the listing is usually printed it can be 
stored on any magnetic-tape or direct- 
access device. For printed output the 
following DD statement will suffice: 

//SYSLOUT DD SYSOUT=A 



Listing (SYSPRINT) 



As well as the information listed in the 
data set defined by the DD statement with 
the name SYSLOUT certain information 
produced by the loader is always stored in 
the data set defined by the DD statement 
with the name SYSPRINT. This data set, 
which must have consecutive organization, 
holds messages that refer to errors that 
have occurred during execution of your 
program, as well as the results produced by 



your program. The information that may 
appear is described in "Listing Produced by 
the Loader," later in this chapter. For 
printed output the following DD statement 
will suffice: 

//SYSPRINT DD SYSOUT=A 



EXAMPLES OF LOADER JCL 



A sequence of job control language for the 
loader is shown in Figure 5-19. A PL/I 
program has been compiled in a job step 
with the step name FLI; the resultant 
object module has been placed in the data 
set defined by the DD statement with the 
name SYSLIN. Eecause this module is to be 
loaded and executed in the same job as the 
compile step, this DD statement can use the 
backward reference, indicated by the 
asterisk, as shown. If the compile and 
load-and-go steps were in different jobs, 
the DD statement would have tc specify a 
permanent data set, cataloged or 
uncataloged. 

The IBM-supplied cataloged procedure 
PLIXCG includes a DD statement with the 
name SYSLIN in both the compile and load- 
and-go procedure steps; you do net need tc 
specify this statement unless you want to 
modify it. The IBM-supplied cataloged 
procedure PLIXG does not include a DD 
statement with the name SYSLIN; ycu irust 
supply one, using the qualified name 
GO. SYSLIN. 

Typical job control language statements 
for the loader are shown in Figure 5-20. 
The example illustrates how to include, in 
the input stream, both an object module fcr 
input tc the loader, and data to be used by 
your program during execution. 

The DD statement with the name SYSLIN 
and the two following unnamed ED statements 
define three data sets that are tc te 
concatenated into one data set to be used 
as input to the loader. The first data set 
is named OBJMOD and contains an object 
module. This data set could be the output 
of the optimizing compiler that has just 
processed your FL/I program. The second 
data set is named MODLIE (MOE55) containing 
a load module that has been given the name 
MOD55 and stored in the library called 
MODLIB. The third data set is an object 
module defined by the ED statement with the 
name IN. This DD statement appears further 
on and has the asterisk notation that 
indicates that the data set defined by this 
statement follows in the input stream. 

The DD statement with the name SYSLIB 
and the unnamed DD statement immediately 
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//LOAD 



JOE 



//STEPl EXEC PGM=LOADER 

//SYSLIN DD DSN-*.PLI.SYSLIN,DISP=( OLD, DELETE) 

//SYSLIB DD DSN=SYSl.PLIBASE,DISP=SHR 

//SYSLOUT DD SYSOUT=A 

//SYSPRINT DD SYSOUT=A 

Figure 5-19. Job control language for load-and-go 



//LOAD 



JOB 



//STEPl EXEC PGM=LOADER 

//SYSLIN DD DSN=OBJECT,UNIT=SYSSQ,VOL=SER=30104,DISP= (OLD, KEEP) 

// ED DSN=MODLIB(MOD55) ,DISP=SHR 

// DD DDNAME=IN 

//SYSLIB DD DSN=SYSl.PLIBASE,DISP=SHR 

// DD DSN=PRIVLIB,DISP=SHR 

//SYSLOUT DD SYSOUT=A 

//SYSPRINT DD SYSOUT=A 

//IN DD * 



(insert here the object module to be loaded) 



/* 

//SYS IN 



DD * 



(insert here the execution data, if any) 



/* 

Figure 5-20. Object and load modules in load-and-go 



following it define two data sets that are 
to be concatenated so that they can be 
searched for unresolved external references 
by automatic library call. The first data 
set is the PL/I resident library 
(SYSl.PLILIB) and the second is a private 
library called PRIVLIB. 



statement that invokes it: 

CALL 

EP 

LET 

WAP 

PRINT 

RES 

SIZE 



Optional Facilities of the Loader 



The loader provides a number of optional 
facilities that are selected by including 
the appropriate keywords from the following 
list in the PARM parameter of the EXEC 



Code the PARK parameter as follows: 

PARK = * [optionlist] C/pgnparir] ' 

where "option list" is a list cf leader 
options, and "pgmparm" is a parameter to be 
passed to the main procedure cf the PL/I 
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program to be executed. xn tne ex 
given below, the program parameter 
referred to as PP. 



In the examples 
is 



If both loader options and a prograir 
parameter occur in the PARM parameter, the 
loader options are given first and are 
separated from the program parameter by a 
slash. If there are loader options but nc 
program parameter, the slash is omitted, 
but if there are only program parameters 
the slash must be coded. If there is more 
than one option, the option keywords are 
separated by commas. 



The PARM field can have one of three 
formats: 



1. If the special characters / cr = are 
used, the field must be enclosed in 
single quotes. For example: 



CAII Option 



The CAII option specifies that the loader 
will attempt to resolve external references 
by automatic library call. To preserve 
compatibility with the linkage editcr, the 
negative form of this option can be 
specified as NCAL as well as by NOCAIL. 



EP Option 



The EP option specifies the entry point 
name cf the program that is to be executed, 
The format of the EF option is: 

EP=name 

where "name" is an external name. If all 
input modules are load modules you irust 
specify EP=FIISTART. 



PARM= * MAP ,EP=FIRST/PP' 

= , MAP,EP=FIRST t 
PARM= ' /PP ' 



IET Option 



2. If these characters are not included, 
and there is more than one loader 
option, the options must be enclosed 
in parentheses. For example: 

PARM=(MAP,LET) 

3. If these characters are not included, 
and there is only one loader option, 
neither quotes nor parentheses are 
required. For example: 

PARM=MAP 

To overwrite the PARM parameter options 
specified in a cataloged procedure, you 
must refer to the PARM parameter by the 
qualified name PARM.procstepname. For 
example: PARM.GO. 

The loader options are of two types: 

1. Simple pairs of keywords: a positive 
form (for example, CALL) that requests 
a facility, and an alternative 
negative form (for example NOCALL) 
that rejects that facility. CALL, 
LET, MAP, PRINT, and RES are of this 
type. 

2. Keywords that permit you to assign a 
value to a function (for exairple, 
SIZE=10K). EP and SIZE are cf this 
type. 

The loader options are described in the 
following sections, in alphabetic order. 



The LET option specifies that the leader 
will try to execute the problem program 
even if a severity 2 error has been found. 



MAP Option 



The MAP option specifies that the loader is 
to print a map of the load nodule giving 
the relative locations and lengths of 
control sections in the nodule. Ycu must 
specify the data set defined by the DD 
statement with the name SYSICUT to have 
this map printed. The module map is 
described in "Listing Produced by the 
Loader," later in this chapter. 



PRINT Option 



The PRINT option specifies that the data 
set defined by the DD statement with the 
name SYSLOUT is to be used for rressages, 
the module map, and other loader 
information. 



RES Option 



The RES option specifies that the loader 
will attempt to resolve external references 
by a search of the link-pack area of main 
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storage. This search will be made after 
the primary input to the loader has been 
processed but before the data set defined 
by the DD statement with the name SYSLIB is 
opened. 



SIZE Option 



The SIZE option specifies the amount of 
main storage, in bytes, to be allocated to 
the loader. The format of the SIZE option 
is: 

SIZE=yyyyyy specifies that yyyyyy bytes of 
main storage are to be 
allocated to the loader. 

SIZE=yyyK specifies that yyyK bytes of 

main storage are to be 
allocated to the loader 
(1K=1024). 

The values can be enclosed, optionally, 
in parentheses. 



Listing Produced by the Loader 



The loader can provide a listing on the 
SYSLOUT data set; the SY SPRINT data set is 
used by the problem program. The contents 
of each is given in Figure 5-21. 



Data set 



Contents 



SYSLOUT Loader explanatory messages and 
diagnostic messages, and 
optionally, a module map. 

SYSPRINT PL/I execution-time messages, 
and problem program output. 

Figure 5-21. Contents of SYSLOUT and 
SYSPRINT data sets 



The SYSLOUT listing is described here; 
the SYSPRINT listing is described in 
Chapter 4 . 

The items in the SYSLOUT listing appear 
in the following sequence: 

1. Statement identifying the loader. 

2. Module map (if specified). 

3. Explanatory, error, or warning 
messages . 

4. Diagnostic messages. 



MODULE MAP 



If the MAP option is specified, a ircdule 
map is printed in the SYSLOUT listing. The 
map lists all the control sections in the 
load module and all the entry point names 
(other than the first) in each control 
section. The information for each 
reference is : 

• The control section or entry point name. 

• An asterisk, if the control section is 
included by automatic library call. 

• An identifier, as follows: 

SD Section definition: the name of 
the control section. 

LR Label reference: identifying an 

entry point in the control section 
other than the priirary entry 
point. 

CM Common area: an external file, or 
a non-string eleirent variable 
declared STATIC EXTERNAL without 
the INITIAL attribute. 

• Absolute address of the control section 
or entry point. 

Each reference is printed left tc right 
across the page and starts at a preset 
position. This gives the iirpressicn that 
the references are arranged in columns, but 
the correct way to read the irap is line by 
line, across the page, not down each 
column. 

The module map is followed by a similar 
listing of the pseudo-registers. The 
identifier used here is PR, and the address 
is the offset from the beginning of the 
pseudo-register vector (PRV) . The total 
length of the PRV is given at the end. 

The total length of the ircdule tc be 
executed, and the absolute address cf its 
primary entry point, are given after the 
explanatory messages and befcre the 
diagnostic messages. 



EXPLANATORY AND DIAGNOSTIC MESSAGES 



The loader generates messages describing 
errors or conditions, detected during 
processing by the loader, that may lead to 
error. The format of these messages is 
given in "Diagnostic Messages and Ccntrol 
Statements" in the linkage editor section 
earlier in this chapter. 
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When the module to be executed has been 
processed, the loader prints out in full 
all the messages referred to above. The 
text of each message, an explanation, and 
any recommended programmer response, are 
given in the linkage editor and loader 
publication. 

The warning message IEW1001 alirost 
always appears in the listing. The 
explanation for this is the same as that 
for IEW0461, described under "Diagnostic 
Message Directory, " in the linkage editor 
section earlier in this chapter. 
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Chapter 6: Data Sets and Files 



This chapter describes briefly the nature 
and organization of data sets, the data 
management services provided by the 
operating system, and the record formats 
acceptable for auxiliary storage devices. 
The way in which a data set is associated 
with a PL/ I file is fully described in the 
language reference manual for this 
compiler. Methods of creating and 
accessing data sets in PL/ I are given in 
Chapters 7 and 8. 



Data Sets 



In IBM System/360 Operating System, a data 
set is any collection of data that can be 
created by a program and accessed by the 
same or another program. A data set may be 
a deck of punched cards; it may be a series 
of items recorded on magnetic tape or paper 
tape; or it may be recorded on a direct- 
access device such as a magnetic disk or 
drum. A printed listing produced by a 
program is a data set, but it cannot be 
accessed by a program. 

A data set resides on one or more 
volumes. A volume is a standard physical 
unit of auxiliary storage (for example, a 
reel of magnetic tape or a disk pack) that 
can be written on or read by an 
input/output device; a serial number 
identifies each volume (other than a 
punched-card or paper-tape volume or a 
magnetic-tape volume either without labels 
or with nonstandard labels) . 



nonstandard unlabeled magnetic tape do net 
have names. 

You can place the name of a data set, 
with information identifying the volume on 
which it resides, in a catalog that exists 
on the volume containing the operating 
system. Such a data set is termed a 
cataloged data set . To catalog a data set 
use the CATLG subparameter cf the DISP 
parameter of the DD statement. To retrieve 
a cataloged data set, you dc net need to 
give the volume serial nuirber or identify 
the type of device; you need only specify 
the name of the data set and its 
disposition. The operating system searches 
the catalog for information associated with 
the name and uses this infornation tc 
request the operator to irount the volume 
containing your data set. 

If you have a set of related data sets, 
you can increase the efficiency of the 
search for a particular data set by 
establishing a hierarchy of indexes in the 
catalog. For example, consider an 
installation that groups its data sets 
under four headings: ENGRNG, SCIENCE, 
ACCNTS, and INVNTRY, as shown in Figure 
6-1. In turn, each of these groups is 
subdivided; for example, the SCIENCE group 
has subgroups called PHYSICS, CHEM, MATH, 
and BIOLOGY. The MATH subgroup itself 
contains three subgroups: ALGEBRA, 
CALCULUS, and BOOL. 



A magnetic-tape or direct- access volume 
can contain more than one data set; 
conversely, a single data set can span two 
or more magnetic-tape or direct-access 
volumes . 



ENGRNG SCIENCE 



ACCNTS INVNTRY 



DATA SET NAMES 



A data set on a direct-access device must 
have a name so that the operating system 
can refer to it. If you do not supply a 
name, the operating system will supply a 
temporary one. A data set on a magnetic- 
tape device must have a name if the tape 
has standard labels (see "Labels," later in 
this chapter.) A name consists of up to 
eight characters, the first of which must 
be alphabetic. Data sets on punched cards, 
paper tape, unlabeled magnetic tape, or 



PHYSICS CHEM MATH BIOLOGY 



I I I 

ALGEBRA CALCULUS BOOL 

Figure 6-1. A hierarchy of indexes 
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To find the data set BOOL r the names of 
all the indexes of which it is part must be 
specified, beginning with the largest group 
SCIENCE, followed by the subgroup name MATH 
and finally the data set name BOOL. The 
names are separated by periods. The 
complete identification needed to find the 
data set BOOL is 



SCIENCE. MATH. BOOL 



Such an identifier is termed a qualified 
name . The maximum length of a qualified 
name is 44 characters, including the 
separating periods; each component name has 
a maximum length of eight characters. (Do 
not use names that begin with the letters 
SYS; if the name is qualified do not use P 
as the nineteenth character. The names 
assigned by the operating system to unnamed 
temporary data sets are of this form, with 
P as the nineteenth character, and these 
data sets are deleted when the utility 
program IEHPROGM is used with a SCRATCH 
statement that includes the keywords VTOC 
and SYS.) 



Some data sets are updated periodically, 
or are logically part of a group of data 
sets, each of which is related to the other 
in time. You can relate such data sets to 
each other in what is termed a generation 
data group . Each data set in a generation 
data group has the same name qualified by a 
unique parenthesized generation number (for 
example, STOCK (0), STOCK (-1), STOCK(-2)>. 
The most recently cataloged data set is 
generation 0, and the preceding generations 
are -1, -2, and so on. You specify the 
number of generations to be saved when you 
establish the generation data group. 

For example, consider a generation data 
group that contains a series of data sets 
used for weather reporting and forecasting; 
the name of the data sets is WEATHER. The 
generations for the group (assuming that 
three generations are to be saved) are: 

WEATHER (0) 
WEATHER (-1) 
WEATHER (-2) 

When WEATHER is updated, the new data 
set is specified to the operating system as 
WEATHER(+1). When it catalogs the new data 
set, the operating system changes the name 
to WEATHER(O), changes the former 
WEATHER(O) to WEATHER (-1), the former 
WEATHER(-l) to WEATHER(-2), and deletes the 
former WEATHER (-2). 

To find out how to create a generation 
data group, refer to the job control 
language and utilities publications. 



BLOCKS AND RECORDS 



The items of data in a data set are 
arranged in fclocks separated by interblock 
gaps (IBG)*-. 

A block is the unit of data transmitted 
to and from a data set. Each block 
contains one record, part of a record, or 
several records. A block cculd alsc 
contain a prefix field of up to 99 bytes in 
length depending on the code (ASCII cr 
EBCDIC) in which the data is recorded. 
These codes are discussed in "Data Cedes," 
below. Specify the block size in the 
BLKSIZE parameter of the DD statement or in 
the BLKSIZE option of the ENVIRONMENT 
attribute. 

A record is the unit of data transmitted 
to and from a program. When writing a PL/I 
program, you need consider enly the records 
that you are reading or writing; but when 
you describe the data sets that ycur 
program will create or access, you must be 
aware of the relationship between blocks 
and records. 

If a block contains two or more records, 
the records are said to be blocked. 
Blocking conserves storage space in a 
volume because it reduces the number of 
input/output operations required to process 
a data set. Records are blocked and 
deblocked automatically by the data 
management routines. 

| Specify the record length in the LRECL 
j parameter of the DD statement or in the 
JRECSIZE option of the ENVIRONMENT 
j attribute. 

Data Codes : The normal code in which data 
is recorded in System/360 is the Extended 
Binary Coded Decimal Interchange Cede 
(EBCDIC) although source input can 
optionally be coded in BCD (Binary Coded 
Decimal). However, f or "magnetic tape only, 
System/360 will accept data recorded in the 
American Standard Code for Information 
Interchange (ASCII). Use the ASCII and 
BUFOFF options of the ENVIRONMENT attribute 
if you are reading or writing data sets 
recorded in ASCII. 

A prefix field up to 99 bytes in length 
may be present at the beginning of each 
block in an ASCII data set. The use of 
this field is controlled by the BUFOFF 
option. For a full description of the 
options used for ASCji, data sets see the 
language reference manuals for this 
compiler^^ .. _„.___' 

1 Although the term "interrecord gap" is 
widely used in operating, system manuals,, it 
is not used here; it has been replaced by 
the more accurate term "interblock gap." 
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RECORD FORMATS 

The records in a data set must have one of 
the following formats : 

• F fixed length 

• V variable length (D- or V- format) 

• U undefined length 

All formats can be blocked if required, 
but only fixed-length and variable-length 
records are deblocked automatically by the 
system; undefined length records trust be 
deblocked by your program. 



records faster than variable-length 
records. The use of "standard" (FS-format 
and FES-format) records further optimizes 
the sequential processing of a data set on 
a direct-access device. A standard format 
data set must contain fixed-length records 
and must have no embedded empty tracks or 
short blocks (apart f roir the last blcck) . 
With a standard format data set, the 
operating systeir can predict whether the 
next block of data will be on a new track 
and, if necessary, can select a new 
read/write head in anticipation of the 
transmission of that block. A PL/ I program 
never places embedded short blocks in a 
data set with fixed-length reccrds. A data 
set containing fixed-length records can be 
processed as a standard data set even if it 
is not created as such, providing it 
contains no embedded short blocks cr empty 
tracks. 



Fixed-length Records (F-format Records) 



Variable-length Records (D- cr V-fcrmat 
Records) 



You can specify the following formats for 
fixed-length records: 

F Fixed- length, unblocked 

FB Fixed-length, blocked 

FS Fixed- length, unblocked, standard 

FBS Fixed- length, blocked, standard 

In a data set with fixed-length records, 
as shown in Figure 6-2, all records have 
the same length. If the records are 
blocked, each block contains an equal 
number of fixed- length records (although 
the last block may be truncated if there 
are insufficient records to fill it). If 
the records are unblocked , each record 
constitutes a block. 



Unblocked records (F-format) : 



r i r i r t r — 

| Record |IBG| Record |IBG| Record |IEG| 

L — . J I J I J I — 



Blocked records (FB-format) : 
r . Block t 



r 1 r 

| Record Record Record | IBG| Record 

L J I 



Figure 6-2. Fixed-length records 



Because it can base blocking and 
deblocking on a constant record length, the 
operating system can process fixed-length 



You can specify the following formats for 
variable- length records: 

V Variable-length, unblocked 

VB Variable-length, blocked 

VS Variable-length, unblocked, spanned 

VBS Variable-length, blocked,, spanned 

D Variable-length, unblocked,, ASCII 

DB Variable-length, blccked, ASCII 

V-format permits both variable-length 
records and variable-length blocks. The 
first four bytes of each reccrd and cf each 
block contain control information for use 
by the operating system (including the 
length in bytes of the record or block) . 
Because of these control fields, variable- 
length records cannot be read backwards. 
Illustrations of variable- length reccrds 
are shown in Figure 6-3. 

V-format signifies unblocked variable- 
length records. Each record is treated as 
a block containing only one record, the 
first four bytes of the block contain block 
control information, and the next fcur 
contain record control information. 

VB-format signifies blocked variable- 
length records. Each block contains as 
many complete records as it can 
accommodate. The first four bytes cf the 
block contain block control information,, 
and the first four bytes cf each reccrd 
contain record control information. 

Spanned Records : A spanned record is a 
variable-length record in which the length 
of the record can exceed the size of a 
block. If this occurs, the record is 
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V-format: 



C1 


C2 


Record 1 



IBG 



C1 


C2 


Record 2 



IBG 



C1 



C2 



VB-format: 



C1 


C2 


Record 1 


C2 


Record 2 



IBG 



C1 



C2 



Record 3 



VS-format: 



C1 


C2 


Record 1 
(entire) 



IBG 



C1 



C2 



Record 2 
(first segment) 



spanned record 
IBG 



C1 



C2 



Record 2 
(last segment) 



IBG 



VBS-format: 



C1 


C2 


Record 1 
(entire) 


C2 


Record 2 
(first segment) 



spanned record 
BG 



C1 



C2 



C1: Block control information 

C2: Record or segment control information 

Figure 6-3. Variable- length records 



Record 2 
(last segment) 



C2 



Record 3 



divided into segments and accommodated in 
two or more consecutive blocks by 
specifying the record format as either VS 
or VBS. Segmentation and reassembly are 
handled automatically. The use of spanned 
records allows you to select a block size, 
independently of record length, that will 
combine optimum use of auxiliary storage 
with maximum efficiency of transmission. 



VS-format is similar to V-format. Each 
block contains only one record or segment 
of a record. The first four bytes of the 
block contain block control information, 
and the next four contain record or segment 
control information (including an 
indication of whether the record is 
complete or is a first, intermediate, or 
last segment) . 

With REGIONAL (3) organization, the use 
of VS-format removes the limitations on 
block size imposed by the physical 
characteristics of the direct-access 
device. If the record length exceeds the 
size of a track, or if there is nc room 
left on the current track for the record, 
the record will be spanned over one or more 
tracks . 



VBS-format differs from VS-f orirat in 
that each block contains as many complete 
records or segments as it can acccirircdate; 
each block is, therefore, approximately the 
same size (although there can be a 
variation of up to four bytes,, since each 
segment must contain at least one byte of 
data) . 

ASCII Records : For data sets that are 
recorded in ASCII use D- format as follows: 

D- format records are similar to V-format 
except that the data they contain is 
recorded in ASCII. 

DB-format records are sirrilar to VB- 
format except that the data they contain is 
recorded in ASCII. 



Undefined-length Records (U -format 
Records) 



U-format permits the processing of records 
that do not conform to F- and v-fcrirats. 
The operating system and the compiler treat 
each block as a record; your program must 
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perform any required blocking or 
deblocking. 



DATA SET ORGANIZATION 



The data management routines of the 
operating system can handle five types of 
data set, which differ in the way data is 
stored within them and in the permitted 
means of access to the data. The three 
main types of data set and the 
corresponding keywords describing their 
PL/I organization* are given in Figure 6-4, 



Type of Data Set 
Sequential 
Indexed sequential 
Direct 



PL/I Organization 
CONSECUTIVE 
INDEXED 
REGIONAL 



Figure 6-4. The three main types of 
data set 



The fourth type, teleprocessing, is 
recognized by the compiler by the file 
attribute TRANSIENT. 

The fifth type, partitioned, has no 
corresponding PL/I organization. 

In a sequential (or CONSECUTIVE) data 
set, records are placed in physical 
sequence. Given one record, the location 
of the next record is determined by its 
physical position in the data set. 
Sequential organization is used for all 
magnetic tapes, and may be selected for 
direct-access devices. Paper tape, punched 
cards, and printed output are sequentially 
organized. 

An indexed sequential (or INDEXED) data 
set must reside on a direct-access volume. 
Records are arranged in collating sequence, 
according to a key that is associated with 
every record. An index or set of indexes 
maintained by the operating system gives 
the location of certain principal records. 
This permits direct retrieval, replacement, 
addition, and deletion of records, as well 
as sequential processing. 



x Do not confuse the terms "sequential" and 
"direct" with the PL/I file attributes 
SEQUENTIAL and DIRECT. The attributes 
refer to how the file is to be processed, 
and not to the way the corresponding data 
set is organized. 



A direct (or REGIONAL) data set irust 
reside on a direct-access volume. The 
records within the data set can be 
organized in three ways: REGIONAL (1), 
REGIONAL(2), and REGIONAL* 3) ; in each case, 
the data set is divided intc regions, each 
of which contains one or more records. A 
key that specifies the regicr number and, 
for REGIONAL (2) and REGIONAL (3), identifies 
the record, permits direct access tc any 
record; sequential processing is also 
possible. 

A teleprocessing data set (associated 
with a TRANSIENT file in a PL/I program) 
must reside in main storage. Records are 
placed in physical sequence; a key eirbedded 
in the record provides direct access to any 
record. 

In a partitioned data set, independent 
groups of sequentially organized data, each 
called a member, reside on a direct-access 
volume. The data set includes a directory 
that lists the location of each member. 
Partitioned data sets are often called 
libraries . The compiler includes no 
special facilities for creating and 
accessing partitioned data sets; however,, 
this is not necessary since each member can 
be processed as a CONSECUTIVE data set by a 
PL/I program, and there is ready access to 
the operating system facilities for 
partitioned data sets through job control 
language. The use of partitioned data sets 
as libraries is described in Chapter 10. 



LABELS 



The operating system uses labels to 
identify magnetic-tape and direct-access 
volumes and the data sets they contain, and 
to store data set attributes (for example, 
record length and block size). The 
attribute information must originally come 
from a DD statement or from your program. 
Once the label is written ycu need net 
specify the information again. 

Magnetic -tape volumes can have standard 
or nonstandard labels, or they can be 
unlabeled. Standard labels have twe parts: 
the initial volume label, and header and 
trailer labels. The initial volume label 
identifies a volume and its owner; the 
header and trailer labels precede and 
follow each data set on the volume. Header 
labels contain system inforiration, device- 
dependent information (for example, 
recording technique) , and data set 
characteristics. Trailer labels are almost 
identical with header labels, and are used 
when magnetic tape is read backwards. 

Direct-access volumes have standard 
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labels. Each volume is identified by a 
volume label, which is stored at a standard 
location on the volume. This label 
contains a volume serial number and the 
address of a volume table of contents 
(VTOC) . The table of contents, in turn, 
contains a label, termed a data set control 
block (DSCB), for each data set stored on 
the volume. 



DATA DEFINITION (DD) STATEMENT 



A data definition (DD) statement is a job 
control statement that defines a data set 
to the operating system, and is a request 
to the operating system for the allocation 
of input/ output resources. Each job step 
must include a DD statement for each data 
set that is processed by the step. 

Chapter 1 describes the format of job 
control statements. The operand field of 
the DD statement can contain keyword 
parameters that describe the location of 
the data set (for example, volume serial 
number and identification of the unit on 
which the volume will be mounted) and the 
attributes of the data itself (for example, 
record format) . 

The DD statement enables you to write 
PL/I source programs that are independent 
of the data sets and input/output devices 
they will use. You can modify the 
parameters of a data set or process 
different data sets without recompiling 
your program; for example, you can cause a 
program that originally read punched cards 
to accept input from magnetic tape merely 
by changing the DD statement. 



Name of DD Sta temen t 



cause the data sets LIST1, LIST2, and UST3 
to be treated as a single data set for the 
duration of the job step in which the 
statements appear: 

//GO. LIST DD DSNAME=LIST1,DISP=0LD 
// DD DSNAME=LIST2,DISP=0LE 

// DD DSNAME=LIST3,DISP=0LE 

When read front a PL/I prcgrair the 
concatenated data sets need not be on the 
same volume, but the volumes roust be on the 
same type of device, and the data sets must 
have similar characteristics (for example, 
block size and record format). You cannot 
process concatenated data sets backwards. 



Parameters of DD Statement 



The operand field of the DD statement 
contains keyword parameters that you can 
use to give the following information: 

• The name of the data set (DSNAME 
parameter) . 

• Description of the device and volume 
that contain the data set (UNIT, VOLUME, 
SPACE, LABEL,, and SYSOUT parameters) . 

• Disposition of the data set before and 
after execution of the job step (EISP 
parameter) . 

• Data set characteristics (DCB 
parameter) . 

The following paragraphs suirirarize the 
functions of these groups of parameters. 
For full details of all the parameters, 
refer to the job control language 
publications. 



The name that appears in the name field of 
the DD statement (ddnarae) identifies the 
statement so that other job control 
statements and the PL/I program can refer 
to it. A ddname must be unique within a 
job step; if two DD statements in one job 
step have the same name, the second 
statement is ignored. Except when 
specifying the concatenation of two or more 
data sets, a DD statement must always have 
a name. 



NAMING THE DATA SET 



The DSNAME parameter specifies the name of 
a newly defined data set or refers to the 
name of an existing data set (for example, 
DSNAME= ROOTS) . You need not specify the 
DSNAME parameter for a temporary data set 
(one that exists only for the duration of 
the job in which it is created) ; the 
operating system will give it a temporary 
name. 



For input only you can concatenate two 
or more sequential or partitioned data sets 
(that is, link them so that they are 
processed as one continuous data set) by 
omitting the ddname from all but the first 
of the DD statements that describe them. 
For example, the following DD statements 



DESCRIBING THE DEVICE AND VOLUME 



The UNIT parameter specifies the type of 
input/output device to be allocated for the 
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data set. You can specify the type by 
giving the actual unit address, the type 
number of the unit (for example, UNIT=2400 
for the 2400 series Nine-track Magnetic 
Tape Drive), or by naming a group of units 
established at system generation (for 
example, UNIT=SYSDA for any direct- access 
device) . 

The VOLUME parameter identifies the 
volume on which the data set resides (for 
example, VOLUME=SER=12345) . It can also 
include instructions for mounting and 
demounting volumes. 

The SPACE parameter specifies the amount 
of auxiliary storage required to 
accommodate a data set on a direct^-access 
device (for example, SPACE=(CYL, 10) 
specifies that 10 cylinders are to be 
allocated) . 

The LABEL parameter specifies the type 
and contents of the data set labels for 
magnetic tape (for example, LABEL=<* 
indicates that the data set is the fourth 
data set on the volume) . 

The SYSOUT parameter allows you to route 
an output data set through a system output 
device (for example, SYSOUT=A) . A system 
output device is any unit (but usually a 
printer or a card punch) that is used in 
common by all jobs. The computer operator 
allocates all the system output devices to 
specific classes according to device type 
and function. The usual convention is for 
class A to refer to a printer and class B 
to a card punch; the IBM-supplied cataloged 
procedures assume that this convention is 
followed. If you use the SYSOUT parameter, 
the only other information you may have to 
supply about the data set is the block 
size, which you can specify either in the 
DCB parameter of the DD statement or in 
your PL/I program. 



DISPOSITION OF THE DATA SET 



The DISP parameter indicates whether a data 
set exists or is new, and specifies what is 
to be done with it at the end of the job 
step (for example, DISP=( NEW, KEEP) 
specifies that a data set is to be created 
and that it is to be kept on the volume of 
the end of the job step). At the end of a 
job step, you can delete a data set, pass 
it to the next step in the same job, enter 
its name in the system catalog or have it 
removed from the catalog, or you can keep 
the data set for future use without 
cataloging it. 

The LEAVE and REREAD options of the 
ENVIRONMENT attribute allow you to use the 



DISP parameter to pontrol the action taken 
when the end of a magnetic-tape volume is 
reached or when a magnetic-tape data set is 
closed. For a description of these options 
refer to the language reference manual for 
this compiler. 



Use of the Conditiona l Subp arameters 



If you wish use the conditional 
subparameters of the DISP parameter for 
data sets processed by PL/I programs, the 
step abend facility must be used. The step 
abend facility is obtained as fellows: 

j 1. The ERROR condition shculd be raised 

or signaled whenever the program is to 
terminate execution after a failure 
that requires the application of the 
conditional subparaireters. 

| 2. The resident library subroutine 

IBMBEER must be changed to return a 
non-zero return code. The irethed of 
doing this is described in Chapter 12 
under the heading "The ABEND 
Facility" . 



DATA SET CHARACTERISTICS 



The DCB (data control block) parameter of 
the DD statement allows you to describe the 
characteristics of the data in a data set, 
and the way it will be processed, at 
execution time. Whereas the other 
parameters of the DD statement deal chiefly 
with the identity, location, and disposal 
of the data set, the DCB parameter 
specifies information required for the 
processing of the records themselves. The 
subparameters of the DCB parameter are 
described in Appendix A. For DCB use, see 
"Data Control Block," later in this 
chapter. 

The DCB parameter contains subparameters 
that describe: 

• The organization of the data set and how 
it will be accessed (CYLOFL, DSORG, 
LIMCT, NCP, NTM, and OPTCD 
subparameters). 

• Device dependent information such as the 
recording technique for iragnetic tape or 
the line spacing for a printer (CODE,, 
DEN, FUNC, MODE, PRTSP , STACK, and TRTCH 
subparameters) . 

• The record format (BLKSIZE, KEYLEN, 
LRECI, RECFM, and RKP subparameters). 
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• The number of buffers that are to be 
used (BUFNC subparameter) . 

• The printer or card punch control 
characters (if any) that will be 
inserted in the first byte of each 
record (RECFM subparameter) . 

You can specify BLKSIZE, BUFNO, LRECL, 
KEYLEN, NCP, RECFM, RKP, and TRKOFL (or 
their equivalents) in the ENVIRONMENT 
attribute of a file declaration in your 
EL/I program instead of in the DCB 
parameter . 

You cannot use the DCB parameter to 
override information already established 
for the data set in your PL/I program (by 
the file attributes declared and the other 
attributes that are implied by them). DCB 
subparameters that attempt to change 
information already supplied are ignored, 
in example of the DCB parameter is: 

ECB=(RECFM=FB,BLKSIZE=400,LRECL=4 0) 

This parameter specifies that fixed- 
length records, 40 bytes in length, are to 
be grouped together in a block 400 bytes 
long. 



Operating System Data Management 



An object module produced by the optimizing 
compiler uses the data management routines 
of the operating system to control the 
storage and retrieval of data. The 
compiler translates each input and output 
statement in a PL/I program into a set of 
machine instructions that result in the 
issuing of assembler language macro 
instructions that request the data 
management routines to perform the required 
input or output operations. (These macro 
instructions are described in the 
supervisor and data management macro 
instructions publication. ) 

The macro instructions are issued either 
directly, by compiled code, or by 
appropriate subroutines from the transient 
library. In the latter case, the compiled 
code includes a branch to an interface 
subroutine in the resident libraa:y that 
initiates the flow of control through other 
required library subroutines. 

The data management routines control the 
organization of data sets, as well as the 
storage and retrieval of the records they 
contain. They create and maintain data set 
labels, indexes, and catalogs; they 
transmit data between main storage and 
auxiliary storage; they use the system 
catalog to locate data sets; and they 



request the operator to mount and demount 
volumes as required. 



BUFFERS 



The data management routines can provide 
areas of main storage,, termed buffers , in 
which data can be collected before it is 
transmitted to auxiliary storage, or into 
which it can be read befcre it is made 
available to a program. The use of buffers 
permits the blocking and deblocking cf 
records, and may allow the data management 
routines to increase the efficiency cf 
transmission of data by anticipating the 
needs of a program. Anticipatory buffering 
requires at least two buffers: while the 
program is processing the data in cne 
buffer, the next block of data can be read 
into another. Anticipatcry buffering can 
only be used for data sets being accessed 
sequentially. 

The operating system can further 
increase the efficiency cf transmission in 
a program that involves many input/cutput 
operations by using chained scheduling . In 
chained scheduling, a series of read or 
write operations are chained together and 
treated as a single operation. Fcr chained 
scheduling to be effective, at least three 
buffers are necessary. For more 
information on chained scheduling see the 
data management services publication. 

The data management routines have two 
ways of making data that has been read into 
a buffer available to a program. In the 
move mode, the data is actually transferred 
from the buffer into the area of main 
storage occupied' by the program. In the 
locate mode, the program can process the 
data while it is still in the buffer; the 
data management routines pass the address 
of the buffer to the program to enable it 
to locate the data. Similarly a program 
can move output data intc the buffer or it 
can build the data in the buffer itself. 



ACCESS METHODS 



Data management has two access techniques 
for transmitting data between main storage 
and auxiliary storage: 

The queued access technique deals with 
individual records, which it blocks and 
deblocks automatically. Records are 
retrieved and written by means of macro 
instructions. The first time a macro 
instruction is issued to retrieve a record, 
the data management routines place a block 
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of records in an input buffer and pass the 
first record to the program that issued the 
instruction (that is, they deblock the 
records); each succeeding retrieval passes 
another record to the program. When the 
input buffer is empty, it is automatically 
refilled with another block. Similarly, 
another macro instruction places records in 
an output buffer and, when the buffer is 
full, writes out the records. Since the 
queued access technique brings records into 
main storage before they are requested, it 
can be used only for records that have been 
stored sequentially. 

The basic access technique uses other 
macro instructions for input and output. 
These instructions move blocks, not 
records. When a macro instruction is 
issued to retrieve a block, the data 
management routines pass a block of data to 
the program that issued the instruction; 
they do not deblock the records. 
Similarly, another macro instruction 
transmits a block to auxiliary storage. 

The combination of data set 
organization, as described earlier in this 
chapter, and an access technique is termed 
an access method . The access methods used 
by the compiler are shown in Figure 6-5. 



QSAM: Queued sequential access method: 
this combines the queued access 
technique with sequential 
or gani za tion . 

QISAM: Queued indexed sequential access 
method: this combines the queued 
access technique with indexed 
sequential organization. 

BSAM: Basic sequential access method: 
this combines the basic access 
technique with sequential 
organization. 

BISAM: Basic indexed sequential access 
method: this combines the basic 
access technique with sequential 
organization. 

BDAM: Basic direct access method: this 
combines the basic access 
technique with direct 
organization. 

TCAM: Telecommunications access method: 
this combines the queued access 
technique with telecommunications 
organization. 

Figure 6-5. The access methods used by 
the compiler 



The PL/I library subroutines use QSAM 
for stream-oriented transmission and all of 
the above methods for record-oriented 
transmission, as shown in Figure 6-6. They 
implement PL/I GET and PUT statements by 
transferring the appropriate number of 
characters from or to the buffers, and use 
GET and PUT macro instructions in the 
locate mode to fill or empty the buffers. 
(For paper tape, however, the library 
subroutines use the move mode to permit 
translation of the transmitted characters 
before passing them to the PL/I program.) 



DATA CONTROL BLOCK 



A data control block (DCB) is an area of 
main storage that contains information 
about a data set and the volume that 
contains it. The data management routines 
refer to this information when they are 
processing a data set; no data set can be 
processed unless there exists a 
corresponding DCB. For a PL/I program, a 
PL/I library subroutine creates a DCE for 
the associated data set when a file is 
opened . 

A data control block contains two types 
of information: data set characteristics 
and processing requirements. The 
characteristics include record format, 
record length, block size, and data set 
organization. The processing information 
may specify the number of buffers to be 
used, and it may include device-dependent 
information (for example, printer line 
spacing or magnetic -tape recording 
density) , and special processing options 
that are available for some data-set 
organiz at ions . 

The information in the DCB comes from 
three sources: 

1. The file attributes declared 
implicitly or explicitly in the PL/I 
program. 

2. The data definition (DD) statement for 
the data set. 

3. If the data set exists, the data set 
labels. 



OPENING A FILE 



The execution of a PL/I OPEN statement 
associates a file with a data set. This 
requires the merging of the information 
describing the file and the data set. If 
any conflict is detected between file 
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Figure 6-6. Access methods for record-oriented transmission 



PL/I PROGRAM 



DD STATEMENT 



DATA SET LABEL 



DCL MASTER FILE ENV(FB BLKSIZE(400) 

RECSIZE(40)); 

OPEN FILE(MASTER); 



//MASTER DD UNIT=2400 



VOLUME=SER= 1791 

DSNAME-LIST, 

DCB=(BUFNO=3, 

RECFM=F, 

BLKSIZE=400, 

LRECL=100) 




Record format=F 
Record length=100 
Blocking factor=4 
Recording density=1600l 



DATA CONTROL BLOCK 



Record format 


FB 


Block size 


400 


Record length 


40 


Device type 


2400 


Number of buffers 


3 


Recording density 


1600 



Note: Information from the PL/I program overrides that from the DD statement and the data set label. 
Information from the DD statement overrides that from the data set label. 



Figure 6-7. Bow the operating system completes the DCB 
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attributes and data set characteristics the 
UNDEFINEDFILE condition will be raised. 

Subroutines of the PL/I library create a 
skeleton data control block for the data 
set, and use the file attributes from the 
DECLARE and OPEN statements, and any 
attributes implied by the declared 
attributes, to complete the data control 
block as far as possible, as shown in 
Figure 6-7. They then issue an OPEN macro 
instruction, which calls the data 
management routines to check that the 
correct volume is mounted and to complete 
the data control block. The data 
management routines examine the data 
control block to see what information is 
still needed and then look for this 
information, first in the DD statement, and 
finally, if the data set exists and has 
standard labels, in the data set labels. 
For new data sets, the data management 
routines begin to create the labels (if 
they are required) and to fill them with 
information from the data control block. 

Neither the DD statement nor the data 
set label can override information provided 
by the PL/I program; nor can the data set 
label override information provided by the 
DD statement. 

When the DCB fields have been filled in 
from these sources, control returns to the 
PL/I library subroutines. If any fields 
have still not been filled in, the PL/I 
OPEN subroutine provides default 
information for some of them; for example, 
if LRECL has not been specified, it is now 
provided from the value given for BLKSIZE. 



IBM 2520 AND 2540 CARD READER AND PUNCH 



Both the card reader and card punch accept 
F-format, V-format, and U-fcrirat records; 
the control bytes of V-format records are 
not punched. Any attempt to block records 
is ignored. 

Each punched card corresponds tc cne 
record; you should therefore restrict the 
maximum record length to 80 bytes (EBCDIC 
mode) or 160 bytes (column- binary mode). 
To select the mode, use the MODE 
subparameter of the DCB parameter of the DD 
statement; if you omit this subparaireter, 
EBCDIC is assumed. (The column-binary mode 
increases the packing density of 
information on a card, punching two bytes 
in each column. Only six bits of each byte 
are punched; on input, the two high-order 
bits of each byte are set tc zero; en 
output, the two high-order bits are lost.) 
The Card Read Punch 2540 has five stackers 
into which cards are fed after reading or 
punching. Two stackers accept only cards 
that have been read, and two others accept 
only those that have been punched; the 
fifth (center) stacker can accept either 
cards that have been read or those that 
have been punched. The two stackers in 
each pair are numbered 1 and 2 and the 
center stacker is numbered 3, as shown in 
Figure 6-8. 



-READ- 



CLOSING A FILE 



1 I 



-PUNCH- 



The execution of a PL/ I CLOSE statement 
dissociates a file from the data set with 
which it was associated. The PL/I library 
subroutines first issue a CLOSE macro 
instruction and, when control returns from 
the data management routines, release the 
data control block that was created when 
the file was opened. The data management 
routines complete the writing of labels for 
new data sets and update the labels of 
existing data sets. 



Auxiliary Storage Devices 



The following paragraphs summarize the 
salient operational features of various 
types of auxiliary storage devices. 



Figure 6-8. Card read punch 2540: 
stacker numbers 



The Card Read Punch 2520 has two 
stackers, into which cards can be read or 
punched. The Card Reader 2501 has only one 
stacker . 

Cards are normally fed into the 
appropriate stacker 1 after reading or 
punching. You can use the STACK 
subparameter of the DCB parameter of the DD 
statement to select an alternative stacker 
for reading or punching. For punching 
only, you can select the stacker 
dynamically by inserting an £NS or 
System/ 360 code in the first byte of each 
record; you must indicate which cede you 
are using in the RECFM subparameter of the 
DD statement or in the ENVIRONMENT option. 
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The control character is not punched. 



Basic Card Reading and Punching 



IBM 3505 AND 3525 CARD READER AND PUNCH 



The 3505 Card Reader and the 3525 Card 
Punch are available only to System/370 
users. These two devices are functionally 
separate and operate independently of each 
other . 



Card reading or punching on a 3525 is 
selected by specifying DCB=(FUNC=R) for 
reading or DCB= (FUNC=P) for punching. If 
the FUNC subparameter is not specified, the 
default is FUNC=R for input files and 
FUNC=P for output files that do not have 
the PRINT attribute. 

Apart from this function selection for 
the 3525, support for the 3505 as a simple 
card reader and the 3525 as a card reader 
or punch is identical to that for the 254 
described earlier x in this chapter. 



The 3505 will read 80- column cards, and 
provides, in addition to normal card 
reading, the following facilities: 

• Optical mark read (in EBCDIC or column 
binary mode) . 

• Read column eliminate (in EBCDIC or 
column binary mode). 

• Stacker selection. 

The 3525 is basically an 80-column card 
punch, and can have the following 
additional facilities: 

• Card reading facilities that optionally 
include: 

Reading in EBCDIC or column binary 
mode. 

Read column eliminate. 

• Card punching in EBCDIC or column binary 
mode. 

• Card printing facilities that include 
either: 

Two- line printing. 

or: 

Multiline printing (up to 25 
lines ) . 

• Punch interpretation. 

• Stacker selection. 



EBCDIC or Column Binary Modes 



Cards processed by a 3505 or a 3525 can 
hold data coded in either EECDIC or column 
binary mode. If EBCDIC is used, each card 
can contain up to 80 characters. If column 
binary is used, each card can contain up to 
160 binary characters, two per card column. 
EBCDIC and column binary data cannot be 
intermixed. 

In column binary mode, each card column 
holds two 6- bit characters. The low-order 
bit appears in row 12 of the card cclumn 
for the first character, and in row 4 for 
the second character. The binary values of 
characters are transmitted to successive 
bytes in main storage. The two high-order 
bits of each byte are set to^ zero (these 
bits are not represented in the 6-bit 
code) . The characters are transmitted in 
the order: first (top) character, second 
(bottom) character, and so on for each 
column in the card, from column 1 tc column 
80. 

The details of the coding and conversion 
technique used for column binary data are 
left to the program designer. The 
TRANSLATE built-in function iray provide a 
convenient method of converting data to or 
from column binary form. 

Rules for using column binary mode are: 

• The MODE subparameter of the DCB 

parameter must specify column binary 
(MODE=C) . 



The various operations of the 3505 and 
the 3525 are described in the following 
sections. In general, the operations to be 
performed are selected by the FUNC, MODE, 
and STACK subparameters of the DCB 
parameter. The formats of these 
subparameters are described in Appendix A 
of this manual. 



The PL/I file must have the RECORD 
attribute. 

The punch -interpret feature must not be 
used. 

The file must be either an input file or 
an output punch file. It cannct be a 
print file. 
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A column binary output file must have a 
record size of 160 bytes. 



Stacker Selection 



The stacker selection feature is optionally 
available on the 35 05 and is a standard 
feature on a 3525. There are two methods 
of selecting a stacker: 

1. The stacker can be selected 
permanently for all cards in the file. 
This method involves the STACK 
subparameter of the DCB parameter. 

2. For record-oriented output files on a 
3525, the first byte of the record can 
contain a stacker control character to 
select the required stacker 
dynamically. The use of such codes is 
specified by the CTLASA or CTL360 
environment options. 



Optical Mark Read 



The optical mark read (OMR) feature is 
available only on the 3505 card reader. 
This feature enables preprinted or pencil- 
written marks on a punched card to be read 
as data. The following rules apply: 

• Optical mark read is specified by 
MODE=EO (EBCDIC mode) or MODE=CO (column 
binary mode) in the DCB parameter. 

• The associated PL/I file must have the 
RECORD and INPUT attributes, and must 
not have the TOTAL attribute. 

• Records must be F- format with a RECSIZE 
of 80 (EBCDIC mode) or 160 (column 
binary mode) . 

• Up to 40 columns of EBCDIC data or 80 
characters of column binary data can be 
read optically from a single card. 
Optical and punched data can be read 
from the same card although there are 
some restrictions, given below, on how 
the data is recorded on the card. 

• Optical mark data can appear only in 
alternate card columns and must be 
separated by blank columns. Optical 
mark and punched hole columns must also 
be seperated by at least one blank 
column. When the record is read in, the 
data is compressed by removing the blank 
column following each optical mark 
column, and the record is padded with 
blanks. 



The columns containing optically- 
readable marks must be specified to the 
program at execution -time by a format 
descriptor card. This card must be the 
first card in the deck of cards to be 
read by the file each time the program 
is run. Operating procedures for 
running jobs that use OMR should ensure 
that this point is not overlooked. 

The OMR descriptor card has the 
following format: 

FORMAT (nl,n2), (n3,n4)... 

where nl is the first column in a group 
to be read in OMR mode, n2 is the last 
column in the group, n3 is the first 
column in the next group, n4 is the last 
column in this group, and so on. 
Remember that only every ether column 
between nl and n2 or n3 and n4 can be 
read in OMR mode. A maximum of 40 
columns of OMR data can be accomodated 
on an 80-column card. nl and n2 (and 
similarly n3 and n4) must be either both 
even or both odd, and n3 must be at 
least 2 greater than n2. 

The format descriptor record must begin 
in column 2 and can continue through 
column 71. If a continuation is 
required, punch any character in column 
72 and start the continuation in column 
16 of the following card. 

A blank must follow the keyword FORMAT. 
Operands must be separated by a comma. 
Example: 

FORMAT (1,9) , (70,80) 

This specifies that columns 1 to 10 and 
70 to 80 are reserved for OMR use and, 
of these, columns 1, 3, 5, 7, 9, 70, 72, 
74, 76, 78, and 8 will be scanned for 
optical mark data. 

Note that column 1 of the card always 
corresponds with the first byte cf the 
data in main storage. Consequently, if 
an optical mark appears in column 2, 
column 1 must be blank and byte 1 will 
also be blank. 

If a marginal mark, weak nark, or poor 
erasure is detected on a column, the 
corresponding byte and the last byte of 
the record are set to X*3F*. The 
TRANSMIT condition is raised once only 
for all errors found in a card. The 
card itself is stacked in the 
alternative stacker to that normally 
used by the file. 

When an optical mark read file is 
closed, the last card is fed and stacked 
in the same stacker as the previous 
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card. This feed operation resets the 
device into unformatted mode, ready for 
the next file opening. 

optical mark read is not supported on 
SYSIN. The 3505 must be allocated 
exclusively to the user's job by 
specifying the device type of the unit 
address in the UNIT parameter of the DD 
statement. 

When a file is opened for optical mark 
reading, the value of the BUFFERS option 
(for BUFFERED files) or the NCP option 
(for UNBUFFERED files) is automatically 
set to 1. 



Read Column Eliminate 



The read column eliminate (RCE) feature is 
optionally available on the 3505 and on a 
3525 with card reading facilities. This 
feature permits the selective reading of 
card columns. The columns to be ignored 
when the card is read are specified in a 
format descriptor card. The ignored 
columns are replaced by blanks in EBCDIC 
mode or zeroes in column binary mode before 
the record is transmitted. 

The following rules apply: 

• Read column eliminate is specified by 
MODE=ER (EBCDIC mode) or M0DE=CR (column 
binary mode) in the DCB parameter. 

• An RCE format descriptor card must be 
supplied. This card must be the first 
card in the deck of cards to be read by 
the program each time it is executed. 
Operating procedures for running jobs 
that use RCE should ensure that this 
point is not overlooked. 

• The RCE descriptor card has the 
following format : 

FORMAT (nl,n2) , (n3,n4). .. 

where nl is the first column in a group 
of columns to be ignored and n2 is the 
last column in the group, n3 is the 
first column in the next group to be 
ignored, n4 is the last column in this 
group, and so on. 

The format descriptor card must begin in 
column 2 and continue through to column 
71. If a continuation is required, 
punch any character in column 72 and 
start the continuation in column 16 of 
the following card. 

A blank must follow the keyword FORMAT. 
Operands must be separated by a comma. 



Example: 

FORMAT (20 ,30) , (52 ,76) 

This specifies that columns 20 through 
30 and columns 52 through 76 are to be 
ignored when the card is read. 

The PL/I file can have either the STREAM 
or the RECORD attribute. Records must 
be F -format. 

When an RCE file is closed, a card feed 
operation is executed by the reader. If 
several files are tc be read 
consecutively - either for successive 
programs in a single batch, or fcr 
several files in a single program - a 
non-data card must separate the files. 

Read column eliminate is not supported 
on SYSIN. The 3505 or 3525 irust be 
allocated exclusively to the user's job 
by specifying the device type of the 
unit address in the UNIT parameter of 
the DD statement. 



Punch Interpret 



A single file can be used tc punch and 
interpret cards by specifying DCB=(FUNC=I) . 
Cards are punched normally, and the same 
data is printed on lines 1 and 3 of the 
card. The first 64 characters are printed 
on line 1; the remaining 16 characters are 
right- justified on line 3. 

A punch interpret file may have the 
STREAM or RECORD and the BUFFERED or 
UNBUFFERED attributes. Records must be F 
format, with a record size of 80, or 81 if 
control characters are being used for 
stacker selection. 



Printing on Cards 

The card printing feature of the 3525 is 
available in two forms: 

1. Two-line printing. 

2. Multiline printing (up to 25 lines). 

Printing can be performed either as the 
only operation on the card, or as one of a 
number of operations on the same card. The 
following rules apply to print-only files. 
The additional requirements for printing 
after reading or punching a card are 
described under "Multiple Operations" later 
in this chapter. 
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The FUNC subparameter of the DCB 
parameter must specify "W" if the 3525 
has the multiline print feature, or "wt" 
if it has the 2-line print feature. If 
FUNC is omitted, FUNC=w is defaulted for 
PL/ I PRINT files. 

The PL/I file may have either the RECORD 
or the STREAM attribute. 

The maximum number of characters that 
can be printed on each line is 64. The 
user must ensure that this limit is not 
exceeded; in particular, on PRINT files, 
LINESIZE should not exceed 64 or data 
will be lost. 

If the 3525 has the two-line print 
feature, and is used by a file with the 
PRINT attribute or by a file using 
CTLASA or CTL360 control characters, 
care should be taken to ensure that no 
attempt is made to print on any line 
other than lines 1 and 3. Such an 
attempt will cause the program to be 
terminated without raising the PL/I 
ERROR condition. If a PRINT file is 
used, and a PAGES I ZE of more than 3 is 
specified, the pagesize is set to 3 when 
the file is opened. 

If the file is a hon-PRINT file, and 
control characters are not used, records 
are printed on lines 1 and 3 
automatically. 

If a 3525 with the multiple print 
feature is used, the file should have a 
maximum pagesize of 25. If a PAGESIZE 
of greater than 25 is specified on a 
PRINT file, the pagesize is set to 25 
when the file is opened. Whatever the 
page size, a PUT PAGE statement for a 
PRINT file will always cause the file to 
be positioned at line 1 of the next 
card. Any attempt to print beyond line 
25 will cause the program to be 
terminated without raising the PL/I 
ERROR condition. 

All the standard ASA control characters 
can be used, with the exception of "+" 
(suppress space before printing). The 
use of the "+" control character, or of 
SKIP(O) on a PRINT file, will cause the 
program to be terminated without raising 
the PL/I ERROR condition. 

Odd numbered lines on a card can be 
reached using "skip to channel" control 
characters , channel numbers being 
defined as follows: 

channel number = (line number + l)/2 

Only channels 1 through 12 are valid. 
Other lines can be reached by using 
"space and print" control characters. 



All lines can be reached by executing 
sufficient WRITE or PUT operations. 



Multiple Operations 



Two or three files may be used in 
association with each other to enable more 
than one of the operations "read", "punch", 
and "print" to be performed on a single 
card during one pass through a 3525. A DD 
statement is required for each operation 
that the device is to perforir, and the 
association of these data sets is specified 
by means of the unit affinity (AFF) 
parameter, together with the FUNC 
subparameter of the DCB parameter. 

For example, for as set of files that 
are to perform the operations read-punch- 
print the association of the data sets and 
the set of operations are specified as 
follows : 

//CARDIN DD UNIT=3525,DCE=(FUNC=RPW) 
//PUNCH DD UNIT=AFF=CARDIN,DCB=(FUNC=RPW) 
//PRINT DD UNIT=AFF=PUNCH,DCE=(FUNC=RPWX) 

Valid FUNC options are listed in 
Appendix A of this manual. Note that the 
FUNC option must specify the complete set 
of associated operations. "X" must be 
added to the FUNC option of the print data 
set. If the 3525 has the two-line print 
feature, T must also be coded on the FUNC 
option of the print data set. 

The following rules apply to multiple 
operations: 

• All the device-associated files irust 
have the RECORD attribute, and must be 
all BUFFERED or all UNBUFFERED. None of 
the files can have the TOTAL option. 
Records must be F-forirat. 

• If stacker selection is required, it can 
only be specified on the punch file, if 
there is one. Either stacker-select 
control characters or static stacker 
selection by means of the STACK 
subparameter can be used. 

• An associated data set carnct be 
allocated to SYSIN or SYSCUT. The 3525 
must be allocated exclusively to the 
user's job by specifying the device type 
of the unit address in the UNIT 
parameter of the ED statement . 

• Data delimiter cards should not be 
punched or printed on, or the first card 
of the following job will be lost. 

Details of how to open and close 
associated files, and of the sequences of 
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operations that can be performed, are given 
in the Language Reference Manual for this 
compiler. 



Data Protection 



not transmitted. 



PRINTER 



To avoid erroneous punching into card 
columns that already contain data , a "data 
protection" option can be used on a punch 
file which is in association with a read 
file. Data Protection is specified by a 
"D" in the FUNC option of the DD statement 
for the punch data set. The user must 
provide an 80-byte data protection image 
(DPI) and linkedit it into SYSl.IMAGELIB 
with a member name of the form FORMxxxx. 
The DPI contains blanks in columns that are 
to be protected, and any alphanumeric 
character in columns that can be punched. 
An assembler language program is used to 
link edit the DPI; an example is given in 
Figure 6-9. 



| //UP EXEC ASMFCL 
| //ASM. SYSIN DD * 
FORMDPI CSECT 



DC 
DC 
DC 
DC 
END 



X'UO' (protected column) 
X'40' (protected column) 
C3456789A' (punch columns) 
70X , 4 0' (protected columns) 



/* 

//LKED.SYSLMOD DD DISP=OLD, 

// DSNAME=SYSl . IMAGELIB (FORMxxxx) 

Figure 6-9. An example of a program to 
link edit the DPI 



A particular DPI is selected by means of 
the the FCB parameter of the DD statement 
for the punch file. For example: 

//PUNCH DD UNIT=AFF=CARDIN, 
// DCB= ( FU NC=RPWD ) , 

// FCB=XXXX 



Data protection cannot be specified for 
column binary cards. 



PAPER TAPE READER 



The paper tape reader accepts F-f ormat and 
U-format records; each u- format record is 
followed by an end-of -record character. 
Use the CODE subparameter of the DCB 
parameter of the DD statement to request 
translation of data from one of the six 
standard paper-tape codes to System/360 
internal representation (EBCDIC). Any 
character found to have a parity error is 



The printer accepts F- format, V-f ormat, and 
U-format records; the control bytes of V- 
format records are not printed. Each line 
of print corresponds to one record; you 
should therefore restrict your record 
length to the length of one printed line. 
Any attempt to block records is ignored. 

You can use the PRTSP subparameter of 
the DCB parameter of the DD statement to 
request the line spacing of your output, or 
you can control the spacing dynamically by 
inserting an ANS or System/360 code in the 
first byte of each record; you must 
indicate which code you are using in the 
RECFM subparameter of the DD statement or 
in the ENVIRONMENT option. The ccntrol 
character is not printed. If you do not 
specify the line spacing, single spacing 
(no blanks between lines) is assumed. 



MAGNETIC TAPE 



Magnetic-tape devices accept D-format, F- 
f ormat, V-f ormat, and U-format records for 
both 9-track and 7 -track magnetic tape with 
the one exception that 7-track magnetic 
tape will not accept V-f ormat records 
unless the data conversion feature is 
available. (The data in the control bytes 
of V- format records is in binary form; in 
the absence of the data conversion feature, 
only six of the eight bits in each byte are 
transmitted to 7-track tape. ) 

Nine-track magnetic tape is standard in 
IBM System/360, but some 24 00 series 
magnetic-tape drives incorporate features 
that facilitate reading and writing 7-track 
tape. The translation feature changes 
character data from EBCDIC (the 8 -bit code 
used in System/360) to BCD (the 6-bit code 
used on 7-track tape) or vice-versa. The 
data conversion feature treats all data as 
if it were in the form of a bit string, 
breaking the string into groups of eight 
bits for reading into main storage, cr into 
groups of six bits for writing on 7-track 
tape; the use of this feature precludes 
reading the tape backwards. To use 
translation or data conversion, include the 
TRTCH (tape recording technique) 
subparameter in the DCB parameter of the DD 
statement. 

The maximum recording density available 
depends on the model number cf the tape 
drive; single- density tape drive units have 
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a maximum recording density of 8 00 bytes 
per inch, and dual-density tape drive units 
have a maximum of 16 00 bytes per inch. For 
9-track tapes, a single- density drive 
offers only the 8 00 bytes per inch density; 
the standard density for a dual- density 
drive is 1600 bytes per inch, but you can 
use the subparameter DEN (density) of the 
DD statement to specify 8 00 bytes per inch. 
For 7 -track tape, the standard recording 
density for both types of drive unit is 200 
bytes per inch; you can use the DEN 
subparameter of the DCB parameter of the DD 
statement to select alternatives of 556 or 
8 00 bytes per inch. 

Note: When a data check occurs on a 
magnetic- tape device with short length 
records (12 bytes on a read and 18 bytes on 
a write) , these records will be treated as 
noise. 



DIRECT-ACCESS DEVICES 



Direct-access devices accept F-forroat, V- 
format, and U-format records. 

The storage space on these devices is 
divided into conceptual cylinders and 
tracks. A cylinder is usually the amount 
of space that can be accessed without 
movement of the access mechanism, and a 
track is that part of a cylinder that is 
accessed by a single read/write head. For 
example, a 2311 disk pack has ten recording 
surfaces, each of which has 200 concentric 
tracks; thus, it contains 2 00 cylinders. 



each of which contains ten tracks. 

When you create a data set on a direct- 
access device, you must always indicate to 
the operating system how much auxiliary 
storage the data set will require. Use the 
SPACE parameter of the DD statement to 
allocate space in terms of blocks, tracks, 
or cylinders. If you request space in 
terms of tracks or cylinders, bear in mind 
that space in a data set on a direct-access 
device is occupied not only ty blocks of 
data, but by control information inserted 
by the operating system; if you use small 
blocks, the control information can result 
in a considerable space overhead. The 
following reference cards contain tables 
that will enable you to determine the 
amount of space you will require: 



2301 Drum Storage Unit, 
Order No. GX2 0-1717 

2302 Disk storage Drive, 
Order No. GX20-1706 

2303 Drum Storage Unit, 
Order No. GX20-1718 

2311 Disk Storage Drive, 
Order No. GX20-1705 

2314 Storage Facility, 
Order No. GX20-1710 

2321 Data Cell Drive, 
Order No. GX20-1704 

3330 Series Disk Storage, 
Order No. GX20-1920 



Chapter 6: Data Sets and Files 
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This chapter describes how to define data 
sets for use with PL/ 1 files that have the 
STREAM attribute. It explains how to 
create and access data sets with 
CONSECUTIVE organization. The essential 
parameters of the DD statements used in 
creating and accessing these data sets are 
summarized in tables, and several examples 
of PL/I programs (complete with JCL) are 
included to illustrate the text. 

Data sets with the STREAM attribute are 
processed by stream-oriented transmission, 
which allows the PL/I program to ignore 
block and record boundaries and treat a 
data set as a continuous stream of data 
items in character form. 

For output, the data management 
subroutines of the PL/ I library convert the 
data items from the program variables into 
character form if necessary, and build the 
stream of characters into records for 
transmission to the data set. 

For input, the library subroutines take 
records from the data set and separate them 
into the data items requested by the 
program, converting them into the 
appropriate form for assignment to the 
program variables. 

Because stream- oriented transmission 
always treats the data in a data set as a 
continuous stream, it can be used only to 
process data sets with CONSECUTIVE 
organization. 



Creating a Data Set 



Any data set created using stream-oriented 
transmission must have CONSECUTIVE 
organization, but it is not necessary to 
specify this in the ENVIRONMENT attribute, 
since it is the default organization. 

Your program deals only with data items, 
and not with records and blocks as they 
will exist in the data set. Accordingly, 
you need not concern yourself with the 
actual structure of the data set beyond 
specifying a block size (which is always 
necessary) , unless you propose to use 
record-oriented transmission to access the 
data set at a later date. 

To create a data set, you must give the 
operating system certain information either 
in your PL/ I program or in the DD statement 



that defines the data set. The following 
paragraphs indicate the essential 
information, and discuss some of the 
optional information you iray supply; the 
ENVIRONMENT attribute and the LINESIZE 
option are discussed fully in the language 
reference manual for this compiler. 



ESSENTIA! INFORMATION 



You must supply the following information, 
summarized in Figure 7-1, when creating a 
data set: 

• Device that will write or punch ycur 
data set (UNIT, SYSOUT, or VOLUME 
parameter of DD statement). 

• Block size: you can specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute or LINESIZE 
option) or in the DD statement (ELKSIZE 
subparameter) . If you do not specify a 
record length, unblocked records are 
assumed and the record length is 
determined from the block size. If you 
do not specify a record format, U-format 
is assumed (except for PRINT files when 
V-format is assumed: see "PRINT Files," 
later in this chapter). 

If you want to keep a magnetic-tape or 
direct-access data set (that is, you do not 
want the operating system tc delete it at 
the end of your job) , the DD statement must 
name the data set and indicate how it is to 
be disposed of (DSNAME and DISP 
parameters). The DISP parameter alone will 
suffice if you want to use the data set in 
a later step but will not need it after the 
end of your job. 

When creating a data set en a direct- 
access device, you must specify the amount 
of space required for it (SPACE parameter 
of DD statement). 

If you want your data set stored on a 
particular magnetic-tape or direct-access 
device, you must indicate the volume serial 
number in the DD statement (SER or REF 
subparameter of VOLUME parameter) . If you 
do not supply a serial number for a 
magnetic-tape data set that you want to 
keep, the operating system will allocate 
one, inform the operator, and print the 
number on your program listing. 

If your data set is to fellow another 
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r 

| | Parameters of DD Statement 


j j When required | What you must state | Parameters 


| | | Output device j UNIT= or SYSOUT= or 
| All | Always j j VOLUME=REF= 


| | | Block size 1 | DCB=(BLKSIZE= .. .) 


j Direct access only | Always | Storage space j SPACE= 
j j j required j 


| Magnetic tape only | Data set not first | Sequence number J LABEL= 
1 | in volume and for j | 
j j magnetic tapes that j j 
j j do not have j | 
j j standard labels j | 


| | Data set to be used | | 

j | by another job step j Disposition j DISP= 

j | but is not required j j 

j j after end of job j j 


j standard labeled j Data set to be kept | Disposition | DISP= 


j | | Name of data set | DSNAME= 


| | Data set to be on | Volume serial number | VOLUME=SER= or 
j j particular volume j j VOLUME=REF= 


^Alternatively, you can specify the block size in your PL/I program by using either 
j the ENVIRONMENT attribute or the LINESIZE option. 



Figure 7-1. creating a data set: essential parameters of DD statement 



data set on a magnetic-tape volume, you 
must use the LABEL parameter of the DD 
statement to indicate its sequence number 
on the tape. 



Accessing a Data Set 



EXAMPLE 



The use of stream-oriented transmission to 
create a data set on a 2311 disk drive is 
shown in Figure 7-2. The data read from 
the input stream by the standard file SYS IN 
includes a field VREC that contains five 
unnamed 7 -character subfields; the field 
NUM defines the number of these subfields 
that contain information. The output file 
WORK transmits to the data set the whole of 
the field FREC and only those subfields of 
VREC that contain information. The data 
set has U-format unblocked records with a 
maximum block size of 400 bytes (defined in 
the statement that declares the file WORK). 
All blocks except the last will contain 
exactly 4 00 bytes. 



A data set accessed using stream-oriented 
transmission need not have been created by 
stream- oriented transmission, but it must 
have CONSECUTIVE organization, and all the 
data in it must be in character form. You 
can open the associated file for input, and 
read the records the data set contains; or 
you can open the file for output, and 
extend the data set by adding records at 
the end. 



To access a data set, you must identify 
it to the operating system in a DD 
statement. The following paragraphs, which 
are summarized in Figure 7-3, indicate the 
essential information you must include in 
the DD statement, and discuss some of the 
optional information you may supply. The 
discussions do not apply to data sets in 
the input stream, which are dealt with in 
Chapter 6. 
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//OPT7#2 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
PEOPLE: PROC OPTIONS (MAIN) ; 

DCL WORK FILE STREAM OUTPUT ENV(U), 
1 REC, 
2 FREC, 

3 NAME CHAR (19) , 
3 NUM CHAR ( 1) , 
3 PAD CHAR (25) , 
2 VREC CHAR (35) , 
IN CHAR (80) DEF REC; 

ON ENDFILE(SYSIN) GO TO FINISH; 

OPEN FILE(WORK) LINESIZE ( 4 00) ; 
MORE: GET FILE (SYSIN) EDIT (IN) (A (80 ) ); 

PUT FILE(WORK) EDIT( IN) (A( 45+7+NUM) ) ; 
GO TO MORE; 
FINISH: CLOSE FILE (WORK); 
END PEOPLE; 
/* 

//GO.WORK DD DSN=PEOPLE f UNIT=2311,SPACE=(CYL, (2, 1) ) r DISP= (NEW,KEEP) , 
// V0L=SER=D186 

//GO. SYSIN DD * 

202 848 DOCTOR 

2 77123 9 PLUMBER VICTOR HAZEL 

5 698635 COOK ELLEN VICTOR JOAN ANN OTTO 

5 418915 LAWYER FRANK CAROL DONALD NORMAN BRENDA 

3 237837 BARBER ALBERT ERIC JANET 

4 158636 CARPENTER GERALD ANNA MARY HAROLD 



R .C .ANDERSON 

B.F.BENNETT 

R.E.COLE 

J.F.COOPER 

A.J.CORNELL 

E.F.FERRIS 

/* 



Figure 7-2. creating a data set with stream-oriented transmission 



ESSENTIAL INFORMATION 



If the data set is cataloged, you need 
supply only the following information in 
the DD statement: 

• The name of the data set (DSNAME 
parameter) . The operating system will 
locate the information describing the 
data set in the system catalog, and, if 
necessary, will request the operator to 
mount the volume containing it . 

• Confirmation that the data set exists 
(DISP parameter) . If you open the data 
set for output with the intention of 
extending it by adding records at the 
end, code DISP=MOD; otherwise, to open 
the data set for output will result in 
its being overwritten. 

If the data set is not cataloged, you 
must, in addition, specify the device that 
will read the data set and, for magnetic- 
tape and direct-access devices, give the 
serial number of the volume that contains 
the data set (UNIT and VOLUME parameters) . 



If the data set is on paper tape or 
punched cards, you must specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute) or in the EC 
statement (BLKSIZE subparameter) . 

If the data set follows another data set 
on a magnetic -tape volume, ycu rcust use the 
LABEL parameter of the DD statement to 
indicate its sequence number on the tape. 



MAGNETIC TAPE WITHOUT STANDARD LABELS 



If a magnetic-tape data set has nonstandard 
labels or is unlabeled, you nust specify 
the block size either in your PL/I program 
(ENVIRONMENT attribute) or in the DD 
statement (BLKSIZE subparameter) . The 
DSNAME parameter is not essential if the 
data set is not cataloged. 

PL/I data management includes no 
facilities for processing nonstandard 
labels, which, to the operating system, 
appear as data sets preceding or following 
your data set. You can either process the 
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Parameters of DD Statement 



When required 



| What you must state 



Parameters 



Always 



Name of data set 



DSNAME= 



Disposition of data set 



DISP= 



I All devices 



If data set not 
cataloged 



| ... 

| Standard labeled 
| magnetic tape and 
J direct access 



Input device 



UNIT= or VOLUME =REF= 



Volume serial number 



VOLUME=SER= 



Magnetic tape: if data set not 
first in volume or which does not 
have standard labels 



Sequence number 



LABEL= 



If data set does not have standard 
labels 



Block size 1 



DCB=(BLKSIZE=...) 



^Alternatively, you can specify the block size in your PL/I program by using either 
the ENVIRONMENT attribute or the LINES IZE option. 



Figure 7-3. Accessing a data set: essential parameters of DD statement 



//OPT7#4 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
PEOPLE: PROC OPTIONS (MAIN) ; 

DCL WORK FILE STREAM INPUT, 
1 REC, 
2 FREC, 

3 NAME CHAR(19) , 
3 NUM CHAR ( 1) , 
3 SERNO CHAR (7 ) , 
3 PROF CHAR (18) , 
2 VREC CHAR (35), 
IN CHAR (80) DEF REC; 

ON ENDFILE(WORK) GO TO FINISH; 

OPEN FILE (WORK) ; 
MORE: GET FILE(WORK) EDIT (IN ,VREC) (A (45) ,A(7*NUM) ) ; 

PUT FILE (SYS PRINT) SKIP EDIT (IN) (A); 
GO TO MORE; 
FINISH: CLOSE FILE(WORK); 
END PEOPLE; 
/* 
//GO. WORK DD DSN= PEOPLE, UNIT=2311,VOL=SER=D186,DISP= (OLD, KEEP) 

Figure 7-4. Accessing a data set with stream-oriented transmission 
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labels as independent data sets or use the 
LABEL parameter of the DD statement to 
bypass them; to bypass the labels code 
LABEL=(2,NL) or LABEL= (,BLP) . 



RECORD FORMAT 



When using stream-oriented transmission to 
access a data set you do not need to know 
the record format of the data set (except 
when you must specify a block size); each 
GET statement transfers a discrete number 
of characters to your program from the data 
stream. 

If you do give record format 
information, it must be compatible with the 
actual structure of the data set. For 
example, if a data set is created with F- 
forroat records, a record size of 600 bytes, 
and a block size of 3600 bytes, you can 
access the records as if they are U- format 
with a maximum block size of 3600 bytes; 
but if you specify a block size of 3500 
bytes, your data will be truncated. 



EXAMPLE 



The program in Figure 7 -4 reads the data 
set created by the program in Figure 7-2 
and uses the standard file SYSPRINT to list 
the data it contains. (SYSPRINT is 
discussed later in this chapter. ) Each set 
of data is read, by the GET statement, into 
two variables: FREC, which always contains 
4 5 characters ; and VREC, which always 
contains 35 characters. At each execution 
of the GET statement, VREC consists of the 
number of characters generated by the 
expression 7*NUM, together with sufficient 
blanks to bring the total number of 
characters to 35. The DISP parameter of the 
DD statement could read simply DISP=OLD; if 
the second term is omitted, an existing 
data set will not be deleted. 



the layout of printed output in stream- 
oriented transmission; the compiler 
automatically inserts printer contrcl codes 
in response to the PAGE, SKIP, and LINE 
options and format items. 

You can apply the PRINT attribute to any 
STREAM OUTPUT file, even if you do net 
intend to print the associated data set 
directly. When a PRINT file is associated 
with a magnetic-tape or direct-access data 
set, the printer control codes have no 
effect on the layout of the data set, but 
appear as part of the data in the records. 

The compiler reserves the first byte of 
each record transmitted by a PRINT file for 
an ANS printer control code, and inserts 
the appropriate codes automatically. A 
PRINT file uses only the five printer 
control codes shown in Figure 7-5. 



Code Action 

b (blank) Space 1 line before printing 

Space 2 lines before printing 
Space 3 lines before printing 

+ No space before printing 

1 Start new page 

Figure 7-5. Printer control codes used 
by a PRINT file 



The compiler handles the PAGE, SKIP, and 
LINE options or format items by padding the 
remainder of the current record with blanks 
and inserting the appropriate contrcl code 
in the next record. If SKIP or LINE 
specifies more than a three line space, the 
compiler inserts sufficient blank records 
with appropriate control codes to 
accomplish the required spacing. In the 
absence of a printer control option or 
format item, when a record is full the 
compiler inserts a blank code (single line 
space) in the first byte of the next 
record. 



Print Files 



Both the operating system and the PL/I 
language include features that facilitate 
the formatting of printed output. The 
operating system allows you to use the 
first byte of each record for a printer 
control code; the control codes, which are 
not printed, cause the printer to skip to a 
new line or page. Tables of printer control 
codes are given in Figures 8-5 and 8-6. In 
a PL/ I program, the use of a PRINT file 
provides a convenient means of controlling 



RECORD FORMAT 



You can limit the length of the printed 
line produced by a PRINT file either by 
specifying a record length in your PL/I 
program (ENVIRONMENT attribute) , in a DD 
statement, or by giving a line size in an 
OPEN statement (LINESIZE option). The 
record length must include the extra byte 
for the printer control code, that is, it 
must be one byte larger than the length of 
the printed line (five bytes larger for V- 
f or mat records) . The value you specify in 
the LINESIZE option refers to the number of 
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//OPT7#6 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
SINE: PROC OPTIONS (MAIN) ; 

DCL TABLE FILE STREAM OUTPUT PRINT, 

TITLE CHAR ( 13) INIT ( 'NATURAL SINES ' ) , 
HEADINGS CHAR (90) INITC 6 12 

24 30 36 42 48 54') , 

PGNO FIXED DEC (2) INIT(l), 
FINISH BIT(l) INIT( , , B) f 
VALUES (0:359,0: 9) FLOAT DEC(6); 

ON END PAGE (TABLE) BEGIN; 
PUT FILE(TABLE) EDIT( 'PAGE ' ,PGNO) (LINE (55) ,COL (87) , A,F (3) ) ; 
IF FINISH= , 0*B THEN DO; 
PGNO=PGNO+l; 
PUT FILE (TABLE) EDIT (TITLE | | ' (CONT' • D) ' , HEADINGS) 

(PAGE, A, SKIP (3), A); 
PUT FILE (TABLE) SKIP (2); 
END; 
END; 

DO 1=0 to 359; 
DO J=0 TO 9; 
VALUES (I , J) =SI ND (I +J/10 ) ; 
END; 
END; 
OPEN FILE(TABLE) PAGESIZE(52) LINESIZE ( 93) ; 
PUT FILE (TABLE) EDIT (TITLE, HEADINGS) (PAGE, A, SKIP ( 3) , A) ; 
DO 1=0 TO 71; 

PUT FILE (TABLE) SKIP (2); 
DO J=0 TO 4; 
K=5*I+J; 

PUT FILE(TABLE) EDIT( K, VALUES (K,* ) ) (F (3) ,10 F(9,4)); 
END; 
END; 
FINISH='1'B; 

PUT FILE (TABLE) LINE (54); 
CLOSE FILE (TABLE); 
END SINE; 
/* 

//GO. TABLE DD DSN=SINES ,UNIT=2311 ,DISP= (NEW,CATLG) , VOI=SER=Dl86, 
// SPACE=(CYL, (1, 1)) 

Figure 7-6. Creating a data set using a PRINT file 
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characters in the printed line; the 
compiler adds the printer control bytes 



The blocking of records has no effect on 
the appearance of the output produced by a 
PRINT file, but it does result in more 
efficient use of auxiliary storage* when the 
file is associated with a data set on a 
magnetic-tape or direct-access device. If 
you use the LINESIZE option, ensure that 
your line size is compatible with your 
block size: for F-forraat records, block 
size must be an exact multiple of (line 
size + 1); for v-format records, block size 
must be at least nine bytes greater than 
line size. 



Although you can vary the line size for 
a PRINT file during execution by closing 
the file and opening it again with a new 
line size, you must do so with caution if 
you are using the PRINT file to create a 
data set on a magnetic-tape or direct- 
access device: you cannot change the 
record format established for the data set 
when the file is first opened. If the line 
size specified in an OPEN statement 
conflicts with the record format already 
established, the UNDEFINEDFILE condition 
will be raised; to prevent this, either 
specify V-format records with a block size 
at least nine bytes greater than the 
maximum line size you intend to use, or 
ensure that the first OPEN statement 
specifies the maximum line size. (Output 
destined for the printer may be stored 
temporarily on a direct-access device, 
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unless you specify a printer by using 
UNIT*, even if you intend it to be fed 
directly to the printer . ) 

Since PRINT files have a default line 
size of 120 characters, you need not give 
any record format information for them. In 
the absence of other information, the 
compiler assumes V-format records; the 
complete default information is: 

BLKSIZE=129 

LRECL=125 

RECFM=VBA 



IBMBSTAl CSECT 

ENTRY IBMBSTAB 
IBMBSTAB EQU * 

DC 



DC 
DC 
DC 
DC 

DC 



DC 
DC 
DC 
DC 
DC 
DC 
END 



C IBMBSTAB' 

H'14' OFFSET OF TAB COUNT 

H'60' PAGES IZE 

H'120' LINESIZE 

H ' ' PAGELENGTH 

(FOR TERMINALS) 
3H'0' FILLERS 

(RESERVED FOR 

FUTURE USE) 



H'5» 

H'25' 

H'49* 

H»73' 

H'97' 

H'121' 



TAB COUNT 
TAB 1 
TAB 2 
TAB 3 
TAB 4 
TAB 5 



Figure 7-7. Tab control library irodule 
IBMBSTAB 



PUT FILE (TABLE) LINE (54) 

causes the ENDPAGE condition to be raised 
to ensure that a number appears at the foot 
of the last page; the preceding statement 
sets the flag FINISH to prevent a further 
set of headings from being written. 

The DD statement defining the data set 
created by this program Includes no record- 
format information; the compiler infers the 
following from the file declaration and the 
line size specified in the statement that 
opens the file TABLE: 



Record format 



Record size 



I Block size 



VBA (the default for a 
PRINT file) 

= 98 (line size + one byte 
for printer control 
character + four bytes for 
record control field) 

=102 (record length + four 
bytes for block control 
field) 



The program in Figure 8-10 uses record- 
oriented transmission to print the table 
created by the program in Figure 7-6. 



Tab Control Table 

Data-directed and list-directed output to a 
PRINT file is automatically aligned on 
preset tabulator positions; the tab 
settings are stored in a table, an 
assembler language control section, in the 
transient library module IBMBSTAB (Figure 
7-7.) 

The standard settings are given in the 
language reference manual for this 
compiler. The functions of the fields in 
the table are as follows: 



EXAMPLE 



Figure 7-6 illustrates the use of a PRINT 
file and the printing options of the 
stream-oriented transmission statements to 
format a table and write it onto magnetic 
tape for printing on a later occasion. The 
table comprises the natural sines of the 
angles from 0° to 359° 54" in steps of 6'. 

The statements in the ENDPAGE on-unit 
insert a page number at the bottom of each 
page, and set up the headings for the 
following page. After the last line of the 
table has been written, the statement: 



OFFSET OF 
TAB COUNT: 



PAGESIZE: 



LINESIZE: 



PAGELENGTH : 



Halfword binary integer that 
defines the field that 
indicates the number of tabs 
to be used. 

Halfword binary integer that 
defines the default page 
size. 

Halfword binary integer that 
defines the default line size. 

Halfword binary integer that 
defines the default page 
length for printing at a 
terminal. The page length is 
the number of lines between 
perforations. It is used for 
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DCL 1 PLITABS STATIC EXT, 
2 (OFFSET I NIT (6) , 
PAGESIZE I NIT (60) , 
LINESIZE INIT(120), 
NO_OF_TABS I NIT (3), 
TAB1 INITC30) , 
TAB2 INIT(60) , 
TAB3 INIT(90)) FIXED BIN (15,0); 



Figure 7-8. PL/T structure PLITABS for 
modifying the standard tab 
settings (alternative 
method) 



output to the terminal in a 
TSO environment because, 
unlike a printer, the terminal 
does not use a control tape to 
determine page length. The 
default value is zero which is 
a special convention to 
indicate unformatted output. 
For further information on how 
the output is formatted at a 
terminal, refer to the TSO 
Terminal User's Guide. 

FILLERS: Reserved for future use. 

Tab count: Number of tab position entries 
in table (maximum 255). If 

| tab count = 0, any specified 

tab positions are ignored: 
each data item is positioned 
at the start of a new line. 

Tab^-Tabn Tab positions within the 

print line. The first position 
is numbered 1 , and the highest 
position is numbered 255. The 
value of each tab should be 
greater than that of the tab 
preceding it in the table; 
otherwise, it will be ignored. 
The first data field in the 
printed output begins at the 
next available tab position. 

The standard PL/I tab settings in 
IBMBSTAB can be overriden. If the linkage 
editor can resolve a reference to PLITABS 
generated by the compiler, the transient 
library module IBMBSTAB will not foe used. 
Instead, the stream-oriented input/output 
routines will refer to the control section 
PLITABS for the tab settings. 

There are two methods of altering the 
tab settings for a particular program. 

One method is to create an assembler- 
language control section called PLITABS and 



include it in the link- editing of the 
program . 

The alternative method is to include a 
PL/I structure in the source program. The 
organization of the structure is similar to 
the assembler-language control section for 
PLITAES given in Figure 7-7. The name of 
the structure must be PLITABS also and it 
must be declared STATIC and EXTERNAL. An 
example of a PL/I structure to create three 
tab settings in positions 30, 60, and 90, 
and use the defaults for page size and line 
size, is given in Figure 7-8. 

The equivalent fields for PAGELENGTH and 
FILLERS are omitted from the structure, and 
the value given in the offset field is set 
to 6. 

Note that the PAGESIZE field in PLITABS 
is used by PLIDUMP to define the pagesize 
for the dump output. 



Standard Files 



PL/I includes two standard files, SYSIN for 
input and SYSPRINT for output. If ycur 
program includes a GET statement that does 
not include the FILE option, the compiler 
inserts the file name SYSIN; if it includes 
a PUT statement without the FILE option, 
the compiler inserts the name SYSPRINT. 

If you do not declare SYSPRINT, the 
compiler will give the file the attribute 
PRINT in addition to the normal default 
attributes; the complete file declaration 
will be: 

SYSPRINT FILE STREAM OUTPUT PRINT EXTERNAL 

Since SYSPRINT is a PRINT file, the 
compiler also supplies a default line size 
of 120 characters and a V-fcrroat record. 
You need give only a minimum of information 
in the corresponding DD statement; if your 
installation uses the usual convention that 
the system output device of class A is a 
printer, the following is sufficient: 

//SYSPRINT DD SYSOUT=A 

If you use one of the IBM-supplied 
cataloged procedures to execute your 
program, even this DD statement is not 
required, since it is included in the GO 
procedure step. 

You can override the attributes given to 
SYSPRINT by the compiler by explicitly 
declaring or opening the file. If you do 
so, bear in mind that this file is also 
used by the error- handling routines of the 
compiler, and that any change you make in 
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the format of the output from SYSPRINT will 
also apply to the format of execution-time 
error messages. When an error message is 
printed, eight blanks are inserted at the 
| start of each line except the first. If 
| you specify a line size of less than 72 
characters, the messages will not be output 
to SYSPRINT. 

The compiler does not supply any special 
attributes for the standard input file 
SYSIN; if you do not declare it, it 
receives only the normal default 
attributes. The data set associated with 
SYSIN is usually in the input stream; if it 
is not in the input stream, you must supply 
full DD information. 
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Chapter 8: Defining Data Sets for Record Files 



This chapter describes how to define data 
sets for use with PL/I files that have the 
RECORD attribute. It explains how to create 
and access data sets for the three types of 
organization: CONSECUTIVE, INDEXED, and 
REGIONAL recognized by PL/I, and how to 
create and access data sets for 
teleprocessing. The essential parameters of 
the DD statements used in creating and 
accessing these data sets are summarized in 
tables, and several examples of PL/I 
programs (complete with JCL) are included 
to illustrate the text. 



Data sets with the RECORD attribute are 
processed by record-oriented transmission 
in which data is transmitted to and from 
auxiliary storage exactly as it appears in 
the program variables; no data conversion 
takes place. A record in a data set 
corresponds to a variable in the program. 



Consecutive Data Sets 



A data set with CONSECUTIVE organization 
can exist on any type of auxiliary storage 
device. Records are stored sequentially in 
the order in which you write them. 



CREATING A CONSECUTIVE DATA SET 



When you create a CONSECUTIVE data set you 
must specify: 

• Device that will write or punch your 
data set (UNIT, SYSOUT, or VOLUME 
parameter of DD statement). 

• Block size: you can specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute) or in the DD 
statement (BLKSIZE subparameter) . If 
you do not specify a record length, 
unblocked records are assumed and the 
record length is determined from the 
block size. If you do not specify a 
record format, U- format is assumed. 



Storage Device 


Parameters of DD statement 






When required 


What you must state 


Parameters 


All 


Always 


Output device 


UNIT= or 
SYSOUT= or 
VOLUME=REF= 




Block size* 


DCB=(BLKSIZE=... 


Direct access 
only 


Always 


Storage space required 


SPACE = 


Magnetic tape 
only 


Data set not fir*st in 
volume and for magnetic 
tapes that do not have 
standard labels 


Sequence number 


LABEL= 


Direct access 
and standard 
labeled magnetic 
tape 


Data set to be used by 
another job step but not 
required at end of job 


Disposition 


DISP= 


Data set to be kept 
after end of job 


Disposition 


DISP= 




Name of data set 


DSNAME= 




Data set to be on 
particular device 


Volume serial number 


VOLUME=SER= 

or 

VOLUME=REF= 



j 1 Alternatively, you can specify the block size in your PL/I program by using the 
ENVIRONMENT attribute. 

L J 

Figure 8-1. Creating a CONSECUTIVE data set: essential parameters of ED statement 
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If you want to keep a magnetic-tape or 
direct- access data set (that is, you do not 
want the operating system to delete it at 
the end of your job) , the DD statement must 
name the data set and indicate how it is to 
be disposed of (DSNAME and EISP 
parameters). The DISP parameter alone will 
suffice if you want to use the data set in 
a later step but will not need it after the 
end of your job. 

When creating a data set en a direct- 
access device, you must specify the amount 
of space required for it (SPACE parameter 
of DD statement). 

If you want your data set stored on a 
particular magnetic -tape or direct- access 
device, you must indicate the vcluire serial 
number in the DD statement (SER or REF 
subparameter of VOLUME parameter) . 

If you do not supply a serial nuirber for 
a magnetic-tape data set that you want to 
keep, the operating system will allocate 
one, inform the operator, and print the 
number on your program listing. 

If your data set is to fcllcw another 
data set on a magnetic-tape volume, you 
must use the LABEL parameter of the DD 
statement to indicate its sequence number 
on the tape. The essential information for 
creating a CONSECUTIVE data set is 
summarized in Figure 8-1. 

The DCB subparameter s of the DD 
statement that apply to CONSECUTIVE data 
sets are listed in Figure 8-2; they are 
described in Appendix A. You can specify 
record format (RECFM) , block size 
(BLKSIZE), record size (LRECL) , and number 
of buffers (BUFNO) in the ENVIRONMENT 
attribute of the DECLARE statement in your 
PL/I program instead of in a DD statement. 



To access a data set, you must identify 
it to the operating system in a DD 
statement. The following paragraphs, which 
are summarized in Figure 8-3, indicate the 
essential information you must include in 
the DD statement, and discuss some of the 
optional information you may supply. The 
discussions do not apply to data sets in 
the input stream, which are dealt with in 
Chapter 6. 



| Subparameter 


Specifies 


| BLKSI ZE 


Maximum number of bytes per 




block 


| BUFNO 


Number of data management 




buffers 


| CODE 


Paper tape: code in which 




the tape is punched 


| DEN 


Magnetic tape: tape 




recording density 


| FUNC 


Card reader or punch: 




function to be performed 


| LRECL 


Maximum number of bytes per 




record 


| MODE 


Card reader or punch: mode 




or operation (column binary 




or EBCDIC and read column 




eliminate or optical mark 




read 


| OPTCD 


Optional data-management 




services and data-set 




attributes 


| PRTSP 


Printer line spacing (0, 1, 




2 , or 3 ) 


| RECFM 


Record format and 




charac teri stic s 


| STACK 


Card reader or punch: 




stacker selection 


| TRTCH 


Magnetic tape: tape 




recording technique for 




7-track tape 



L J 



ACCESSING A CONSECUTIVE DATA SET 



Figure 8-2. 



DCB subparameter s for 
CONSECUTIVE data sets 



You can access a CONSECUTIVE data set in 
three ways. You can open the associated 
file for input, and read the records the 
data set contains; you can open the file 
for output, and extend the data set by 
adding records at the end; or you can open 
the file for update, and read and rewrite 
each record in turn. (The operating system 
does not permit updating a CONSECUTIVE data 
set on magnetic tape; you must read the 
data set and write the updated records into 
a new data set.) 



Essential Information 

If the data set is cataloged, you need 
supply only the following information in 
the DD statement: 

• The name of the data set (BSNAME 

parameter). The operating systeir will 
locate the information describing the 
data set in the system catalog, and, if 
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Parameters of DD Statement 



When required 



What you must state 



Parameters 



Always 



Name of data set 



DSNAME= 



Disposition of data set 



DISP= 



jAll devices 



Input device 



UNIT= or VOLUME =REF= 



If data set not | 

cataloged | Standard labeled 
| magnetic tape and 
j direct access 



Volume serial number 



VOLUME =SER= 



Magnetic tape: if data set not 
first in volume or which does not 
have standard labels 



Sequence number 



LABEL= 



If data set does not have standard 
labels 



Block size 1 



DCB=(BLKSIZE=...) 



^Alternatively, you can specify the block size in your PL/I program by using either 
the ENVIRONMENT attribute or the LINESIZE option. 



Figure 8-3. Accessing a CONSECUTIVE data set: essential parameters of DD statement 



necessary, will request the operator to 
mount the volume containing it. 

• Confirmation that the data set exists 
CDISP parameter) . If you open the data 
set for output with the intention of 
extending it by adding records at the 
end, code DISP=MOD; otherwise, to open 
the data set for output will result in 
its being overwritten. 

If the data set is not cataloged, you 
must, in addition, specify the device that 
will read the data set and, for magnetic- 
tape and direct-access devices, give the 
serial number of the volume that contains 
the data set (UNIT and VOLUME parameters) . 

If the data set is on paper tape or 
punched cards, you must specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute) or in the DD 
statement (BLKSIZE subparameter) . 

If the data set follows another data set 
on a magnetic -tape volume , you must use the 
LABEL parameter of the DD statement to 
indicate its sequence number on the tape. 



Magnetic Tape Without standard Labels 



If a magnetic-tape data set has nonstandard 
labels or is unlabeled, you must specify 
the block size either in your PL/I program 



(ENVIRONMENT attribute) or in the DD 
statement (BLKSIZE subparameter). The 
DSNAME parameter is net essential if the 
data set is not cataloged. 

PL/I data management includes nc 
facilities for processing nonstandard 
labels which to the operating systeir appear 
as data sets preceding or following your 
data set. You can either process the 
labels as independent data sets or use the 
LABEL parameter of the DD statement to 
bypass them; to bypass the labels code 
LABEL= (2 ,NL) or LABEL= ( ,BLP) . 



Record Format 



If you give record-format information, it 
must be compatible with the actual 
structure of the data set. For example, if 
a data set is created with F-format 
records, a record size of 600 bytes „ and a 
block size of 3600 bytes, you can access 
the records as if they are U-fcrmat with a 
maximum block size of 3600 bytes; but if 
you specify a block size of 3500 bytes, 
your data will be truncated. 



EXAMPLE OF CONSECUTIVE DATA SETS 



Creating and accessing CONSECUTIVE data 
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//OPT8#4 JOB 
//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
MERGE : PROC OPTI ONS ( MAI N ) ; 



DCL (INl,IN2,OUT) FILE RECORD SEQUENTIAL, 

(ITEM1 BASED (A) , ITEM2 BASED(B)) CHARC80); 

ON ENDFILE(INl) BEGIN; 
ON ENDFILE(IN2) GO TO FINISH; 
WRITE FILE (OUT) FROM(ITEM2); 
READ FILE (IN 2) SET(B) ; 
GO TO NEXT2; 
END; 

ON ENDFILE(IN2) BEGIN; 
ON ENDFILE(INl) GO TO FINISH; 
WRITE FILE (OUT) FROM (ITEMl) ; 
READ FILE(INl) SET (A); 
GO TO NEXTl; 
END; 



NEXT2: 



NEXTl: 



NEXT: 



FINISH: 

/* 

//GO. OUT 

// 

//GO. INI 

//GO.IN2 

/* 



OPEN FILE(INl) INPUT, 
FILE(IN2) INPUT, 
FILE (OUT) OUTPUT; 
READ FILE (INI) SET (A); 
READ FILE(IN2) SET(B) ; 
IF ITEM1XETEM2 THEN DC- 
WRITE FILE(OUT) FROM(ITEM2) ; 

READ FILE(IN2) SET(B); 

GO TO NEXT; 

END; 
ELSE DO; 

WRITE FILE (OUT) FROM(ITEMl); 

READ FILE (INI) SET (A) ; 

GO TO NEXT; 

END; 
CLOSE FILE(INl), FILE (IN2), FILE (OUT); 
END MERGE; 

DD DSN=DS3 ,UNIT=2311 ,DCB= (RECFM=FB, BLKSIZE=400, IRECI=80) , 

DISP= (NEW, KEEP), VOL=SER=Dl86,SPACE= (CYL, (1,1)) 
DD * 

(insert here data to be included in the input stream) 
DD * 

(insert here data to be included in the input stream) 



Figure 8-4. Creating and accessing a CONSECUTIVE data set 



sets on magnetic tape are illustrated in 
the program of Figure 8-4. The program 
merges the contents of two existing data 
sets, DSl and DS2 , and writes them onto a 
new data set, DS3; each of the original 
data sets contains 15 -byte fixed-length 
records arranged in EBCDIC collating 
sequence. The two input files, INI and 
IN2, have the default attribute BUFFERED, 
and locate mode is used to read records 
from the associated data sets into the 
respective buffers. 



PUNCHING CARDS AND PRINTING 



You cannot use a PRINT file for reccrd- 
oriented transmission, and record-oriented 
transmission statements cannct include the 
printing options (PAGE, SKIP, etc). You can 
still exercise some control ever the layout 
of printed output by including a printer 
control code as the first byte of each of 
your output records; you can also use 
similar control codes to select the stacker 
to which cards punched by ycur program are 
fed. 
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The operating system recognizes two 
types of code for printer and card punch 
commands, ANS code and machine code. You 
must indicate which code you are using, 
either in your PL/ 1 program (ENVIRONMENT 
attribute), or in the DD statement (RECFM 
subparameter) . If you specify one of these 
codes, but transmit your data to a device 
other than a printer or a card punch, the 
operating system will transmit the control 
bytes as part of your records. If you use 
an invalid control code, "space 1 line" or 
"stacker 1" will be assumed. 

The ANS control codes, which are listed 
in Figure 8-5, cause the specified action 
to occur before the associated record is 
printed or punched. 



The machine control codes differ 
according to the type of device. The codes 
for the 1403 Printer are listed in Figure 
8.6, and Figure 8-7 gives those for the 
2 540 Card Read Funch. Control codes for 
the 3525 card printer are given in Figures 
8-8 and 8-9. 



| Code 




Action | 


1 h 


Space 


» 1 line before printing | 




(blank code) 


1 o 


Space 


i 2 lines before printing | 


| 


Space 


s 3 lines before printing j 


| + 


Suppress space before printing | 


1 1 


Skip 


to channel 1 | 


1 2 


Skip 


to channel 2 | 


1 3 


Skip 


to channel 3 | 


1 " 


Skip 


to channel 4 j 


1 5 


Skip 


to channel 5 j 


1 6 


Skip 


to channel 6 j 


1 1 


Skip 


to channel 7 j 


1 8 


Skip 


to channel 8 j 


1 9 


Skip 


to channel 9 j 


1 A 


Skip 


to channel 10 j 


1 B 


Skip 


to channel 11 j 


1 c 


Skip 


to channel 12 


1 v 


Select stacker 1 | 


1 w 


Select stacker 2 | 


1 The channel 


numbers refer to the printer 


1 carriacre control tape. (See IBM 1403 | 


1 Printer Component Description.) I 



Figure 8-5. ANS printer and card punch 
control codes 
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r 

| Print and then act | 


Action 




Act immediately 










(no printing) 


j Code byte j 


Code byte 


| 00000001 | 


Print only (no £ 


space) 


- 


| 00001001 | 


Space 1 


line 




00C01011 


| 00010001 | 


Space 2 


lines 




00010011 


| 00011001 | 


Space 3 


lines 




00011011 


( 10001001 | 


Skip to 


channel 


1 


10C01011 


| 10010001 | 


Skip to 


channel 


2 


10C10011 


| 10011001 | 


Skip to 


channel 


3 


10011011 


| 10100001 | 


Skip to 


channel 


4 


10100011 


| 10101001 | 


Skip to 


channel 


5 


10101011 


| 10110001 | 


Skip to 


channel 


6 


10110011 


| 10111001 | 


Skip to 


channel 


7 


10111011 


| 11000001 | 


Skip to 


channel 


8 


11C00011 


| 11001001 | 


Skip to 


channel 


9 


11C01011 


| 11010001 | 


Skip to 


channel 


10 


11010011 


J 11011001 | 


Skip to 


channel 


11 


11011011 


| 11100001 | 


Skip to 


channel 


12 


11100011 


jThe channel numbers refer 


to the printer carriage control tape. 


(See IBM 1403 printer 


I Component Description.) 











Figure 8-6. 14 03 printer control codes 



Code byte 

00000001 
01000001 
10000001 



| Action 

| Select stacker 1 
j Select stacker 2 
j Select stacker 3 



L . -,_. J 



Figure 8-7. 



2540 Card Read Punch 
control characters 



CTLASA code | 




Action 



Space 1 
Space 2 
Space 3 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 
Skip to 



line and print 
lines and print 
lines and print 
channel 1 and 



channel 

channel 

channel 

channel 

channel 

channel 

channel 

channel 

channel 10 and 

channel 11 and 

channel 12 and 



and 
and 
and 
and 
and 
and 

8 and 

9 and 



print 
print 
print 
print 
print 
print 
print 
print 
print 
print 
print 
print 



CTL360 code 


Action 




bytes 










00001101 


Print 


on 


line 


1 


00010101 


Print 


on 


line 


2 


00011101 


Print 


on 


line 


3 


00100101 


Print 


on 


line 


4 


00101101 


Print 


on 


line 


5 


00110101 


Print 


on 


line 


6 


00111101 


Print 


on 


line 


7 


01000101 


Print 


on 


line 


8 


01001101 


Print 


on 


line 


9 


01010101 


Print 


on 


line 


10 


01011101 


Print 


on 


line 


11 


01100101 


Print 


on 


line 


12 


01101101 


Print 


on 


line 


13 


01110101 


Print 


on 


line 


14 


01111101 


Print 


on 


line 


15 


10000101 


Print 


on 


line 


16 


10001101 


Print 


on 


line 


17 


10010101 


Print 


on 


line 


18 


10011101 


Print 


on 


line 


19 


10100101 


Print 


on 


line 


20 


10101101 


Print 


on 


line 


21 


10110101 


Print 


on 


line 


22 


10111101 


Print 


on 


line 


23 


11000101 


Print 


on 


line 


24 


11001101 


Print 


on 


line 


25 



l J 



Figure 8-8. 3525 card printer control 
code (CTLASA) 



Figure 8-9. 



3525 card printer control 
codes (CTL360) 
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//OPT8#10 JOB 

//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
PRT: PROC OPTIONS ( MAIN) ; 

DCL TABLE FILE RECORD INPUT SEQUENTIAL, 
PRINTER FILE RECORD OUTPUT SEQL ENV(V BLKSIZE(102) CTLASA) , 
LINE CHAR (94) VAR; 

ON ENDFILE( TABLE) GO TO FINISH; 

OPEN FILE (TABLE) , FILE (PRINTER) ; 
NEXT: READ FILE(TABLE) INTO(LINE); 

WRITE FILE (PRINTER) FROM (LINE) ; 
GO TO NEXT; 
FINISH: CLOSE FILE (TABLE) , FILE (PRINTER) ; 
END PRT; 
/* 

//GO. TABLE DD DSNAME=SINES, DISP=OLD 
//GO. PRINTER DD SYSOUT=A 

Figure 8-10. Printing with record -oriented transmission 



There are two types of command for the 
printer, one causing the action to occur 
after the record has been transmitted, and 
the other producing immediate action but 
transmitting no data (you must include the 
second type of command in a blank record) . 

The essential requirements for producing 
printed output or punched cards are exactly 
the same as those for creating any other 
CONSECUTIVE data set (described above). 
For a printer , if you do not use one of the 
control codes , all data will be printed 
sequentially, with no spaces between 
records ; each block will be interpreted as 
the start of a new line. When you specify 
a block size for a printer or card punch, 
and are using one of the control codes, 
include the control bytes in your block 
size; for example, if you want to print 
lines of 100 characters, specify a block 
size of 101. 



printer control code. The information 
given in the ENVIRONMENT attribute cculd 
alternatively have been given in the DD 
statement, as follows: 

DCB=(RECFM=VA,BLKSIZE=102) 



Indexed Data Sets 



A data set with INDEXED organization can 
exist only on a direct-access device. Each 
record in the data set is identified by a 
key that is recorded with the record. A key 
is a string of not more than 255 
characters; all the keys in a data set must 
have the same length. The records in the 
data set are arranged according to the 
collating sequence of their keys. Once an 
INDEXED data set has been created, the keys 
facilitate the direct retrieval, addition, 
and deletion of records. 



Example 



The program in Figure 8-10 uses record- 
oriented transmission to read and print the 
contents of the data set SINES, created by 
the PRINT file in Figure 7-6. Since the 
data set SINES is cataloged, only two 
parameters are required in the DD statement 
that defines it. The output file PRINTER 
is declared with the ENVIRONMENT option 
CTLaSA, specifying that the first byte of 
each record will be interpreted as an ANS 



INDEXES 



To provide faster access to the reccrds in 
the data set, the operating system creates 
and maintains a system of indexes tc the 
records in the data set. The lowest level 
of index is the track index . There is a 
track index for each cylinder in the data 
set; it occupies the first track (or 
tracks) of the cylinder, and lists the keys 
of the last records on each track in the 
cylinder. A search can then be directed to 
the first track that has a key that is 
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Master index 



450 



Cylinder index 



• 200 



500 



1000 



300 



600 



1200 



375 



700 



1500 



Cylinder 1 



100 


100 


200 


200 


Data 
10 


Data 
20 


Data 
40 


Data 
100 


Data 
150 


Data 
175 


Data 
190 


Data 
200 





Track 
index 

Prime 
data 

Prime 
data 

Overflow 



450 



900 



2000 



900 






2000 



Cylinder 11 



1500 



Cylinder 12 



2000 



Figure 8-11. Index structure of an INDEXED data set 



higher than or equal to the key of the 
required record. 

If the data set occupies more than one 
cylinder, the operating system develops a 
higher level index called a cylinder index . 
Each entry in the cylinder index identifies 
the key of the last record in the cylinder. 
To increase the speed of searching the 
cylinder index, you can request in a DD 
statement that the operating system develop 
a master index for a specified number of 
cylinders; you can have up to three levels 
of master index; Figure 8-11 illustrates 
the index structure. The part of the data 
set that contains the cylinder and master 
indexes is termed the index area . 

When an INDEXED data set is created, all 
the records are written in what is called 
the prime data area . If more records are 
added later, the operating system does not 
rearrange the entire data set; it inserts 
each new record in the appropriate position 
and moves up the other records on the same 
track. Any records forced off the track by 
the insertion of a new record are placed in 
an overflow area . The overflow area can 
consist either of a number of tracks set 
aside in each cylinder for the overflow 
records from that cylinder ( cylinder 
overflow area ) , or a separate area for all 
overflow records ( independent overflow 
area). Figure 8-12 shows how records are 



added to an INDEXED data set. 

Each entry in the track index consists 
of two parts: 

1. The normal entry,, which points to the 
last record on the track. 

2. The overflow entry, which contains the 
key of the first record transferred to 
the overflow area and also points to 
the last record transferred from the 
track to the overflow area. 

If there are no overflow records from 
the track, both index entries point to the 
last record on the track. An additional 
field is added to each record that is 
placed in the overflow area. It points to 
the previous record transferred from the 
same track; the first record from each 
track is linked to the corresponding 
overflow entry in the track index. 



CREATING AN INDEXED DATA SET 



When you create an INDEXED data set, your 
program must write the records in the data 
set sequentially in the order of ascending 
key values; the associated file must be 
opened for SEQUENTIAL OUTPUT. 
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Figure 8-12. Adding records to an INDEXED data set 
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You can use a single DD statement to 
define the whole of the data set (index 
area, prime area, and overflow area), or 
you can use two or three statements to 
define the areas independently. If you use 
two DD statements, you can define either 
the index area and the prime area together, 
or the prime area and the overflow area 
together. 

If you want the whole of the data set to 
be on a single volume, there is no 
advantage to be gained by using more than 
one DD statement except to define an 
independent overflow area (see "overflow 
Area," later in this chapter). But, if you 
use separate DD statements to define the 
index and/or overflow area on volumes 
separate from that which contains the prime 
area, you will increase the speed of direct 
access to the records in the data set by 
reducing the number of access mechanism 
movements required. 

When you use two or three DD statements 
to define an INDEXED data set, the 
statements must appear in the order: index 
area; prime area; overflow area. The DD 
statement must have a name (ddname) , but 
the name fields of a second or third DD 
statement must be blank. The DD statements 
for the prime and overflow areas must 
specify the same type of unit (UNIT 
parameter). You must include all the DCB 
information for the data set in the first 
DD statement; DCB=DSORG=IS will suffice in 
the other statements. 

An INDEXED data set consisting of fixed- 
length records can be extended by adding 
records sequentially at the end, until the 
original space allocated for the prime data 
is filled. The corresponding file must be 
opened for sequential output and you must 
include DISP=MOD in the DD statement. 



Essential Information 



To create an INDEXED data set, you must 
give the operating system certain 
information either in your PL/I program or 
in the DD statement that defines the data 
set. The following paragraphs indicate the 
essential information, and discuss some of 
the optional information you may supply; 
the ENVIRONMENT attribute and the LINESIZE 
option are discussed fully in the language 
reference manual for this compiler. 

You must supply the following 
information when creating an INDEXED data 
set: 

• Device that will write or punch your 

data set (UNIT or VOLUME parameter of DD 



statement) . 

• Block size: you can specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute or LINESIZE 
option) or in the DD statement (ELKSIZE 
subparameter) . If you do not specify a 
record length, unblocked records are 
assumed and the record length is 
determined from the block size. 

If you want to keep a direct-access data 
set (that is, you do not want the operating 
system to delete it at the end of ycur 
job) , the DD statement must name the data 
set and indicate how it is 'to be disposed 
of (DSNAME and DISP parameters). The DISP 
parameter alone will suffice if you want to 
use the data set in a later step but will 
not need it after the end of your jcb. 

If you want your data set stored en a 
particular direct-access device, you must 
indicate the volume serial number in the DD 
statement (SER or REF subparameter of 
VOLUME parameter) . If you dc not supply a 
serial number for a data set that you want 
to keep, the operating system will allocate 
one, inform the operator, and print the 
number on your program listing. All the 
essential parameters required in a ED 
statement for the creation of an INDEXED 
data set are summarized in Figure 8-13, and 
Figure 8-14 lists the DCB subparameters 
needed. 

Appendix A contains a description of the 
DCB subparameters. 

You cannot place an INDEXED data set on 
a system output (SYSOUT) device. 

You must request space for the prime 
data area in the SPACE parameter. Your 
request must be in units of cylinders 
unless you place the data set in a specific 
position on the volume (by specifying a 
track number in the SPACE parameter) . In 
the latter case, the number of tracks you 
specify must be equivalent to an integral 
number of cylinders, and the first track 
must be the first track of a cylinder other 
than the first cylinder in the volume. You 
can also use the SPACE parameter to specify 
the amount of space to be used for the 
cylinder and master indexes (unless you use 
a separate DD statement for this purpose) . 
If you do not specify the space for the 
indexes, the operating system will use part 
of the independent overflow area; if there 
is no independent overflow area, it will 
use part of the prime data area. 

In the DCB parameter, you roust always 
specify the data set organization 
(DSORG=IS) , and in the first (or only) DD 
statement you must also specify the length 
of the key (KEYLEN) . 
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r - ■- - — i 
| Parameters of DD Statement I 


| When required | What you must state | Parameters j 


| | Output device | UNIT= or VOLUME=REF= | 


| | Storage space required | SPACE= j 


j j Data control block | j 
| j information: refer to j DCB= j 
j | figure 8-14. j | 


j | Name of data set and | j 
JMore than one DD statement j area (index, prime, j DSNAME= j 
j j overflow) j j 


j Data set to be used in another job | | j 
jstep but not required after end of | Disposition j DISP= j 
|j°b I I 1 


JData set to be kept after end of | Disposition | DISP= j 


| j Name of data set | DSNAME= j 


(Data set to be on particular | Volume serial number | VOLUME=SER= or j 
j volume j | VOLUME=REF= j 



Figure 8-13. creating an INDEXED data set; essential parameters of DD statement 



Name of Data Set 



Record Format and Keys 



If you use only one DD statement to define 
your data set, you need not name the data 
set unless you intend to access it in 
another job. But, if you include two or 
three DD statements, you must specify a 
data set name, even for a temporary data 
set. 



The DSNAME parameter in a DD statement 
that defines an INDEXED data set not only 
gives the data set a name, but it also 
identifies the area of the data set to 
which the DD statement refers: 



DSNAME=name (I NDEX) 

DSNAME=name (PRIME) 

DSNAME=name (OVFLOW) 

If the data set is temporary, prefix its 
name with the characters "66". If you use 
one DD statement to define the prime and 
index or prime and overflow area, code 
DSNAME =name (PRIME) ; if you use one DD 
statement, code DSNAME=name( PRIME), or 
simply DSNAME=name. 



An INDEXED data set can contain either 
fixed-length or variable -length records, 
blocked or unblocked. You must always 
specify the record format either in your 
PL/ I program (ENVIRONMENT attribute) or in 
the DD statement (RECFM subparaireter) . 

The key associated with each reccrd can 
be contiguous with or embedded within the 
data in the record; you can save storage 
space in the data set if you use blocked 
records with embedded keys. 

If the records are unblocked, the key of 
each record is recorded in the data set in 
front of the record even if it is also 
embedded within the record, as shown in (a) 
and (b) of Figure 8-15. If blocked records 
do not have embedded keys, the key of each 
record is recorded within the block in 
front of the record, and the key of the 
last record in the block is also recorded 
in front of the block, as shown in (c) of 
Figure 8-15. When blocked records have 
embedded keys, the individual keys are not 
recorded separately in front of each record 
in the block; the key of the last record in 
the block is recorded in frcnt of the 
block, as shown in (d) of Figure 8-15. 

If you use blocked records with non- 
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r 


DCB subparameters 




| When required 


To specify 


| Subparameters 


II 


Record formats- 


|RECFM=F, FB, FBS, 
|V, or VB 


j These are always required 


Block size 1 


|BLKSIZE= 


Data set organization 


|DSORG=IS 




Key length 


|KEYLEN= 


j Include at least one of 
j these if overflow is 
jrequired 


Cylinder overflow area and 
number of tracks per cylinder for 
overflow records 


1 

|OPTCD=Y and CYLOFL= 

1 


Independent overflow area 


|OPTCD=I 




Record lengths- 


|LRECL= 




Embedded key (relative key position) 


|RKP= 


j These are optional 


Master index 


|OPTCD=M 




Automatic processing of dummy records 


|OPTCD=L 




Number of data management buffers 3 - 


|BUFNO= 




Number of tracks in cylinder index 
for each master index entry 


|NTM= 
1 


j 1 Alter natively, can be spec] 


Lfied in ENVIRONMENT attribute. 





Note ; Full DCB information must appear in the first, or only, DD statement. Subsequent 
statements require only DSORG=IS. 

Figure 8-14. DCB subparameters for an INDEXED data set 



embedded keys, the record size that you 
specify must include the length of the key, 
and the block size must be a multiple of 
this combined length. Otherwise, record 
length and block size refer only to the 
data in the record. Record format 
information is shown in Figure 8-16. 

If you use records with embedded keys, 
you must include the DCB subparameter RKP 
to indicate the position of the key within 
the record. For fixed-length records the 
value specified in the RKP subparameter is 
one less than the byte number of the first 
character of the key; that is, if RKP=1, 
the key starts in the second byte of the 
record. The value assumed if you omit this 
subparameter is RKP=0, which specifies that 
the key is not embedded in the record but 
is separate from it. 

For variable-length records, the value 
specified in the RKP subparameter must be 
the relative position of the key within the 
record plus four. The extra four bytes take 



into account the 4- byte control field used 
with variable-length records. For this 
reason you must never specify RKP less than 
four. When deleting records you must 
always specify RKP equal to or greater than 
five, since the first byte cf the data is 
used to indicate deletion. 

For unblocked records, the key, even if 
embedded, is always recorded in a position 
preceding the actual data. Consequently, 
the RKP subparameter need net be specified 
for unblocked records. 



Overflow Area 



If you intend to add records to the data 
set on a future occasion, ycu must request 
either a cylinder overflow area or an 
independent overflow area, cr both. 

For a cylinder overflow area, include 
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(a) Unblocked records, non-embedded keys 



Key 


Data 




Key 


Data 




Key 


Data 



(b) Unblocked records, embedded keys 
Data 



f_ 



J 



same key 
(c) Blocked records, non-embedded keys 



Data 



Key 


Key 


Data 


Key 


Data 


Key 


Data 



same key 



Key 



Key 



Data 



Key 




Key 






Key 




Key 






Key 




Key 





(d) Blocked records, embedded keys 
Data 


Data 






Data 




Key 




Key 






Key 






Key 





same key 



(e) Unblocked variable length records, RKP>4 
Data 



Key 


B1 


R1 




Key 





same key 



(f) Blocked variable length records, RKP>4 
■■■ Data 



Data 



same key 



(g) Unblocked variable length records, RKP=4 
A Data s 



Key 


B1 


Rl| Key 





same key 



i 



(h) Blocked variable length records, RKP=4 











Data 






Data 






# : Data s, 


Key 


B1 


R1 


Key 




R1 


Key 




R1 


Key 





same key 



Key 



Data 



Key 


B1 


R1 




Key 




R1 




Key 




R1 




Key 





Figure 8-15. Record formats in an INDEXED data set 
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RKP 



Blocked 
records 



| Not zero 



| Zero or 
| omitted 



| Not zero 

Unblocked j 

records j Zero or 

j omitted 



LRECL 



R + K 



BLKSIZE 



R * B 



B* (R+K) 



R = Size of data in record 

K = Length of keys (as specified in 
KEYLEN subparameter) 

B = Blocking factor 

Example: For blocked records, 

non-embedded keys, 100 bytes of 
data per record, 10 records per 
block, key length = 20: 
LRECL=120,BLKSIZE=1200,RECFM=FB 



Figure 8-16. Record format information 
for an INDEXED data set 



the DCB subparameter OPTCD=Y and use the 
subparameter CYLOFL to specify the number 
of tracks in each cylinder to be reserved 
for overflow records. A cylinder overflow 
area has the advantage of a short search 
time for overflow records, but the amount 
of space available for overflow records is 
limited, and much of the space may be 
unused if the overflow records are not 
evenly distributed throughout the data set. 

For an independent overflow area, use 
the DCB subparameter OPTCD=I to indicate 
that overflow records are to be placed in 
an area reserved for overflow records from 
all cylinders, and include a separate DD 
statement to define the overflow area. The 
use of an independent area has the 
advantage of reducing the amount of unused 
space for overflow records, but entails an 
increased search time for overflow records. 

It is good practice to request cylinder 
overflow areas large enough to contain a 
reasonable number of additional records and 
an independent overflow area to be used as 
the cylinder overflow areas are filled. 

If the prime data area is not filled 
during creation, you cannot use the unused 
portion for overflow records, nor for any 
records subsequently added during direct 
access (although you can fill the unfilled 
portion of the last track used). You can 
reserve space for later use within the 



prime data area by writing "dummy" records 
during creation: see "Dummy Records," 
later in this chapter. 



Master Index 



If you want the operating system to create 
a master index for you, include the DCB 
subparameter OPTCD=M, and indicate in the 
NTM subparameter the number of tracks in 
the cylinder index you wish to be referred 
to by each entry in the master index. The 
operating system will automatically create 
up to three levels of master index, the 
first two levels addressing tracks in the 
next lower level of the master index. 



Duirmy Records 



You cannot change the specification of an 
INDEXED data set after you have created it. 
Therefore, you must foresee your future 
needs where the size and location of the 
index, prime, and overflow areas are 
concerned, and you must decide whether you 
want the operating system to identify and 
skip dummy (deleted) records. 

If you code 0PTCD=L, the operating 
system will identify any record that is 
named in a DELETE statement by placing the 
bit string (8)'1*B in the first byte. 
Subsequently, during SEQUENTIAL processing 
of the data set, such records will be 
ignored; if they are forced cff a track 
when the data set is being updated, they 
will not be placed in the overflew area. 
Do not specify 0PTCD=L when using blocked 
or variable-length records with ncn- 
embedded keys; if you do, the string 
(8)*1'B will overwrite the key of the 
"deleted" record. 

You can include a dummy record in an 
INDEXED data set by setting the first byte 
of data to (8)'l* B and writing the record 
in the usual way. 



ACCESSING AN INDEXED DATA SET 



You can open an INDEXED data set for 
sequential or direct access, and for input 
or update in each case. Sequential input 
allows you to read the records in ascending 
key sequence, and in sequential update you 
can read and rewrite each record in turn; 
during sequential access,, if 0PTCE=L is 
specified when the data set is created, 
dummy records are ignored. Using direct 
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| Parameters of DD Statement 


| When required | What you must state | Parameters 


| | Name of data set | DSNAME= 


| | Disposition of data set | DISP= 


j | Data control block | DCB= 
| | information j 


| | Input device | UNIT= or VOLUME=REF= 


| j Volume serial number | VOLUME=SER= 



Figure 8-17. Accessing an INDEXED data set: essential parameters of DD statement 



input, you can read records using the READ 
statement, and in direct update you can 
read or delete existing records or add new 
ones. 

To access an INDEXED data set, you must 
define it in one, two or three DD 
statements; the DD statements must 
correspond with those used when the data 
set is created. The following paragraphs 
indicate the essential information you must 
include in each DD statement, and Figure 
8-17 summarizes this information. 

If the data set is cataloged, you need 
supply only the following information in 
each DD statement: 

• The name of the data set (DSNAME 
parameter). The operating system will 
locate the information that describes 
the data set in the system catalog and, 
if necessary, will request the operator 
to mount the volume that contains it. 

• confirmation that the data set exists 
(DISP parameter) . 

| • Full DCB information for the first, or 

| only, DD statement. Subsequent 

j statements require only DSORG=IS to be 

I coded. 



of records to the data set results in an 
increasing number of records in the 
overflow area. Therefore, even if the 
overflow area does not eventually become 
full, the average time required for the 
direct retrieval of a record will increase. 
The frequency of reorganization depends on 
how often the data set is updated, en how 
much storage is available in the data set, 
and on your timing requirements . 

Reorganizing the data set also 
eliminates records that are marked as 
"deleted," but are still present within the 
data set. 

There are two ways to reorganize an 
INDEXED data set: 

1. Read the data set into an area of main 
storage or onto a temporary 
CONSECUTIVE data set, and then 
recreate it in the original area of 
auxiliary storage. 

2. Read the data set seguentially and 
write it into a new area of auxiliary 
storage; you can then release the 
original auxiliary storage. 



If the data set is not cataloged, you 
must, in addition, specify the device that 
will process the data set and give the 
serial number of the volume that contains 
it (UNIT and VOLUME parameters) . 



REORGANIZING AN INDEXED DATA SET 



It is necessary to reorganize an INDEXED 
data set periodically because the addition 



EXAMPLES OF INDEXED DATA SETS 



The creation of a simple INDEXED data set 
is illustrated in Figure 8-18. The data 
set contains a telephone directory, using 
the subscribers* names as keys to the 
telephone numbers. 

The program in Figure 8-19 updates this 
data set and prints out its new contents. 
The input data includes the following codes 
to indicate the operations required: 
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//OPT8#18 JOB 
//STEP1 EXEC PLIXCLG 
//PLI. SYSIN DD * 
TELNOS : PROC OPTIONS (MAIN) ; 

DCL DIREC FILE RECORD SEQUENTIAL KEYED ENV ( INDEXED) , 
CARD CHARC80), 

NAME CHAR(20) DEF CARD POS (1) , 
NUMBER CHAR (3) DEF CARD POS(21) r 
IOFIELD CHAR (3); 

ON ENDFILE(SYSIN) GO TO FINISH; 

OPEN FILE( DIREC) OUTPUT; 
NEXTIN: GET FILE (SYSIN) EDIT (CARD) (A (80) ) ; 
IOFIELD=NUMBER; 

WRITE FILE (DIREC) FROM ( I OFI ELD ) KEYFROM(NAME) ; 
GO TO NEXTIN; 
FINISH: CLOSE FILE(DIREC); 
END TELNOS; 
/* 
//GO. DIREC DD DSNAME=TELNO (INDEX) ,UNIT=2311 , SPACE= (CYL r 1) , 



// DCB= (RECFM=F f BLKSIZE=3,DSQRG=IS,KEYLEN=20,OPTCD=LIY ,CYLOFL=2) , 


// DISP=(NEW, 


KEEP) ,V0LUME=SER=D186 


// DD DSNAME=TELNO(PRIME),UNIT=2311,SPACE=(CYL,4) ,DCB=DSORG=IS, 


// DISP=(NEW, 


KEEP) ,V0LUME=SER=D186 


// DD DSNAME=TELNO(OVFLOW) ,UNIT=2311,SPACE= (CYL, 4) , 


// DCB=DSORG=IS,DISP=( NEW, KEEP) , VOL=SER=Dl86 


//GO. SYSIN DD * 




ACTION, G. 


162 


BAKER, R. 


152 


BRAMLEY,O.H. 


248 


CHEESEMAN,D. 


141 


CORY,G. 


336 


ELLIOTT,D. 


875 


FIGGINS,S. 


413 


HARVEY,C.D.W. 


2 05 


HASTINGS, G.M. 


391 


KENDALL, J. G. 


2 94 


LANCASTER,W.R. 


624 


MILES, R. 


233 


NEWMAN, M.W. 


4 50 


PITT,W.H. 


515 


ROLF,D.E. 


114 


SHEERS, CD. 


241 


SUTCLIFFE,M. 


472 


TAYLOR,G.C. 


4 07 


WILTON, L.W. 


404 


WINSTONE,E.M. 


3 07 


/* 





Figure 8-18. Creating an INDEXED data set 



A: Add a new record 

C: Change an existing record 

D: Delete an existing record 



REGIONAL data set is divided into regions 
that are numbered consecutively froir zero. 
The following paragraphs briefly describe 
the three types of REGIONAL organization. 



Regional Data Sets 



A data set with REGIONAL organization can 
exist only on a direct-access device. A 



REGIONAL(l): In this organization a region 
is a record. Each record in the data set 
is identified by its region number, an 
unsigned decimal integer not exceeding 
16777 215. Region numbers start from at 
the beginning of the data set. 
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//OPT8#19 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
DIRUPDT: PROC OPTIONS (MAIN) ; 

DCL DIREC FILE RECORD KEYED ENV ( INDEXED ) , 
ONCODE BUILTIN, 
NUMBER CHAR (3), 
NAME CHAR (20) , 
CODE CHAR (2); 

ON ENDFILE(SYSIN) GO TO PRINT? 

ON KEY (DIREC) BEGIN; 
IF ONCODE=51 THEN PUT FILE (SYS PRINT) SKIP EDIT 
( 'NOT FOUNDS »;NAME) (A (15) ,A) ; 
IF ONCODE=52 THEN PUT FILE (SYSPRINT ) SKIP EDIT 
( 'DUPLICATE: ' f NAME) (A(15) ,A) ; 
END; 

OPEN FILE( DIREC) DIRECT UPDATE; 
NEXT: GET FILE(SYSIN) EDIT (NAME, NUMBER, CODE) (A(20) ,A(3) ,X(56) ,A(1) ) ; 

IF CODE='A' THEN WRITE FILE(DIREC) FROM(NUMBER) KEYFROM (NAME) ; 

ELSE IF CODE='C THEN REWRITE FILE (DIREC) FROM(NUMBEF) 

KEY (NAME); 

ELSE IF CODE=*D' THEN DELETE FILE (DIREC) KEY ( NAME) ; 

ELSE PUT FILE (SYS PRINT) SKIP EDIT( 'INVALID CODE: ' ,NAME) 

(A(15),A); 

GO TO NEXT; 
PRINT: CLOSE FILE (DIREC); 

PUT FILE (SYS PRINT) PAGE; 

OPEN FILE (DIREC) SEQUENTIAL INPUT; 

ON ENDFILE (DIREC) GO TO FINISH; 

NEXTIN: READ FILE (DIREC) INTO( NUMBER) KEYTO(NAME); 

PUT FILE (SYSPRINT) SKIP EDIT (NAME, NUMBER) (A) ; 

GO TO NEXTIN; 
FINISH: CLOSE FILE (DIREC); 

END DIRUPDT; 
/* 

//GO. DIREC DD DSN=TELNO( INDEX) , UNIT=2311,VOL=SER=D186 ,DISP= (OLD,KEEP) 
// DD DSN=^TELNO (PRIME) ,UNIT=2311,VOL=SER=D186,DISP=( OLD, KEEP) 

// DD DSN=TELN0(0VFL0W),UNIT=2311,V0L=SER=D186,DISP= (OLD, KEEP) 

//GO.SYSIN DD * 

NEWMAN, M. W. 516 C 

GOODFELLOW,D.T. 889 A 

MILES, R. D 

HARVEY, CD. W. 209 A 

BARTLETT,S.G. 183 A 

CORY,G. D 

READ,K.M. 001 A 

PITT,W.H. 

ROLF,D.F. D 

ELLIOTT, D. 291 C 

HASTINGS, G.M. D 

BRAMLEY,O.H. 439 C 

/* 

Figure 8-19. Updating an INDEXED data set 
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REGIONAL(l) data sets have no recorded 
keys. Note, however, that PL/I REGIONAL(l) 
DIRECT INPUT or UPDATE files can be used to 
process data sets that do have recorded 
keys. In particular, REGIONAL (2) and 
REGIONAL (3) data sets can be acessed by a 
file declared as ENV (REGIONAL (1)) . 



REGIONAL(2): This organization is similar 
to REGIONAL (1) , but differs, in that a key 
is recorded with each record. The recorded 
key is a string of not more than 255 
characters. For files with the DIRECT 
attribute, a record is written in the first 
vacant space on the track that contains the 
region number specified in the WRITE 
statement; for retrieval, the search for a 
record begins on the track that contains 
the region number specified in the READ 
statement, and may continue through the 
data set until the record has been found. 
For files that are created sequentially, 
the record is written in the region 
specified. 



REGIONALO): This organization is similar 
to REGIONAL (2), but differs in that each 
region corresponds to one track of the 
direct-access device and is not a record 
position. Depending on the record length, 
a region can contain one or more records. 

The major advantage of REGIONAL 
organization over other types of data set 
organization is that it allows you to 
control the relative placement of records; 
by judicious programming, you can optimize 
record access in terms of device 
capabilities and the requirements of 
particular applications. REGIONAL (1) 
organization is most suited to applications 
where there will be no duplicate region 
numbers, and where most of the regions will 
be filled (reducing wasted space in the 
data set). REGIONAL (2) and REGIONALO) are 
more appropriate where records are 
identified by numbers that are thinly 
distributed over a wide range. You can 
include in your program an algorithm that 
derives the region number from the number 
that identifies a record in such a manner 
as to optimize the use of space within the 
data set; duplicate region numbers may 
occur but, unless they are on the same 
track, their only effect might be to 
lengthen the search time for records with 
duplicate region numbers. 

REGIONAL(l) and REGIONAL (2) data sets 
can contain only F- format unblocked 
records, but a REGIONALO) data set can 
have unblocked records of all three 
formats, F, V, and U. The examples at the 
end of this section illustrate typical 
applications of all three types of REGIONAL 
organization . 



CREATING A REGIONAL DATA SET 



You can use either sequential or direct- 
access to create a REGIONAL data set. 

In sequential creation, you must present 
records in order of ascending region 
numbers; for REGIONAL(l) and REGIONALO) 
the region number for each record must 
exceed that of the preceding record since 
each region can contain only cne record. 
In all cases, dummy records (identified by 
OVl^E- in the first byte) are placed 
automatically in regions whose numbers are 
| skipped. The data set ban have up to 15 
| extents, which may be on more than one 
I volume. 

For direct creation, one of the PL/ I 
library subroutines formats the whole of 
the data set when you open the 
corresponding file. For REGIONAL (1) and 
(2), and for REGIONALO) with F-fcrirat 
records, formatting involves filling the 
data set with dummy records; for 
REGIONALO) with U- format or V-format 
records, a record, called the capacity 
record is written at the start of each 
track to indicate an empty track. Luring 
creation, you can present records in any 
| order. The data set can have only cne 
| extent, and can therefore reside on only 
one volume. 



Essential Information 



To create a REGIONAL data set, you must 
give the operating system certain 
information either in your PL/I program or 
in the DD statement that defines the data 
set. The following paragraphs indicate the 
essential information, and discuss some of 
the optional information you may supply; 
the ENVIRONMENT attribute and the LINESIZE 
option are discussed fully in the language 
reference manual for this compiler. 

You must supply the following 
information when creating a REGIONAL data 
set: 

• Device that will write or punch y cur 
data set (UNIT or VOLUME parameter of DD 
statement) . 

• Block size: you can specify the block 
size either in your PL/I program 
(ENVIRONMENT attribute or LINESIZE 
option) or in the DD statement (BLKSIZE 
subparameter) . If you do net specify a 
record length, unblocked records are 
assumed and the record length is 
determined from the block size. 
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r 

| Parameters of DD Statement 


| When required | What you must state | Parameters 


| | Output device | UNIT= or VOLUME=REF= 


| | Storage space required | SPACE= 


j j Data control block | 

j j information: refer j DCB= 

j jto figure 8-21 j 


JData set to be used in another job | | 

j step but not required in another j Disposition j DISP= 

jjob | j 


JData set to be kept after end of | Disposition | DISP= 


| | Name of data set | DSNAME= 


JData set to be on particular | Volume serial number | VOLUME=SER= or 
jvolume | j VOLUME=REF= 



Figure 8-20. Creating a REGIONAL data set: essential parameters of DD statement 



r 


DCB 


S ubparameter s 




| When required 




To specify 


| Subparameters 


j These are always required 




Record formats- 


| RECFM=F 

1 or 

| RECFM=V a REGIONAL (3) only 

1 or 

| RECFM=U REGIONAL (3) only 


Block size 1 


| BLKSIZE= 




Data set organization 


| DSORG=DA 




Key length (REGIONAL (2) 
and (3) only) 


| KEYLEN= 


j These are optional 




Limited search for a 
record or space to add 
a record (REGIONAL (2) 
and (3) only) 


| LIMCT= 




Number of data 
management buffers 1 


| BUFNO= 


j x Alternatively, can be speci 
j 3 RECFM=VS must be specified 
j update. 


.fiec 
in 1 


1 in ENVIRONMENT attribute 
^he ENVIRONMENT attribute 


for sequential input or 



Figure 8-21. DCB subparameters for a REGIONAL data set 



Chapter 8: Defining Data Sets for Record Files 119 



If you want to keep a data set (that is, 
you do not want the operating system to 
delete it at the end of your job) , the DD 
statement must name the data set and 
indicate how it is to be disposed of 
(DSNAME and DISP parameters). The DISP 
parameter alone will suffice if you want to 
use the data set in a later step but will 
not need it after the end of your job. 

If you want your data set stored on a 
particular direct-access device, you must 
indicate the volume serial number in the DD 
statement (SER or REF subparameter of 
VOLUME parameter) . If you do not supply a 
serial number for a data set that you want 
to keep, the operating system will allocate 
one, inform the operator, and print the 
number on your program listing. All the 
essential parameters required in a DD 
statement for the creation of a REGIONAL 
data set are summarized in Figure 8-20, and 
Figure 8-21 lists the DCB subparameters 
needed. Appendix A contains a description 
of the DCB subparameters. 

You cannot place a REGIONAL data set on 
a system output (SYSOUT) device. 

In the DCB parameter, you must always 
specify the data set organization as direct 
by coding DSORG=DA. For REGIONAL (2) and 
REGIONALO), you must also specify the 
length of the recorded key (KEYLEN): refer 
to the language reference manual for this 
compiler for a description of how the 
recorded key is derived from the source key 
supplied in the KEYFROM option. 

For REGIONAL(2) and REGIONALO), if you 
want to restrict the search for space to 
add a new record, or the search for an 
existing record, to a limited number of 
tracks beyond the track that contains the 
specified region, use the LIMCT 
subparameter of the DCB parameter. If you 
omit this parameter, the search will 
continue to the end of the data set, and 
then from the beginning of the data set 
back to the starting point in the data set. 



ACCESSING A REGIONAL DATA SET 



You can open an existing REGIONAL data set 
for sequential or direct access, and for 
input or update in each case. Using 
sequential input with a REGIONAL(l) data 
set you can read all the records in 
ascending region number sequence, and in 
sequential update you can read and may 
rewrite each record in turn. Sequential 
access of a REGIONAL (2) or REGIONALO) data 
set will give you the records in the order 
in which they appear in the data set, which 
is not necessarily region number order. 



Using direct input, you can read any record 
by supplying its region number and, for 
REGIONALO) and REGIONALO), its recorded 
key; in direct update, you can read or 
delete existing records or add new ones. 
The operating system ignores dummy records 
in a REGIONALO) or REGIONALO) data set; 
but a program that processes a REGIONAL (1) 
data set must be prepared tc recognize 
dummy records. 

To access a REGIONAL data set, you must 
identify it to the operating system in a ED 
statement. The following paragraphs 
indicate the minimum information you must 
include in the DD statement; this 
information is summarized in Figure 8-22. 

If the data set is cataloged, you need 
supply only the following information in 
your DD statement: 

• The name of the data set (DSNAME 
parameter) . The operating system will 
locate the information that describes 
the data set in the system catalog and, 
if necessary, will request the operator 
to mount the volume that contains it. 

• Confirmation that the data set exists 
(DISP parameter). 

If the data set is not cataloged, you 
must, in addition, specify the device that 
will read the data set and give the serial 
number of the volume that contains the data 
set (UNIT and VOLUME parameters) . 



EXAMPLES OF REGIONAL DATA SETS 



REGIONAL (1) Data Sets 



Creating a REGIONAL (1) data set is 
illustrated in Figure 8-23. 

The program uses the same data as that 
in Figure 8-18, but interprets it in a 
different way: the data set is effectively 
a list of telephone numbers with the names 
of the subscribers to whom they are 
allocated. The telephone numbers 
correspond with the region numbers in the 
data set, the data in each occupied region 
being a subscriber's name. The SPACE 
parameter of the DD statement requests 
space for 1000 twenty- byte records (that 
is, for 1000 regions); since space is never 
allocated in units of less than one track 
and one 2311 track can accommodate 45 
twenty-byte records, there will in fact be 
1035 regions. Note that the data set has 
no recorded keys because it is created 
using a DIRECT OUTPUT file. 
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Parameters of DD Statement 



When required 


| What you must state 


| Paraireters 


Always 


| Name of data set 


| DSNAME= 




1 

| Disposition of data set 


| DISP= 


If data set not cataloged 


| Input device 
1 


| UNIT= or 

| VOLUME =REF= 



| Volume serial number 



| VOLUME=SER= 



L . J 



Figure 8-22. Accessing a REGIONAL data set: essential parameters of DD statement 



Updating a REGIONAL(l) data set is 
illustrated in Figure 8-24. The data read 
by the program is identical with that used 
in Figure 8-1 9 , and the codes are 
interpreted in the same way. Like the 
program in Figure 8-19, this program 
updates the data set and lists its 
contents. Before each new or updated 
record is written the existing record in 
the region is tested to ensure that it is a 
dummy; this is necessary because a WRITE 
statement can overwrite an existing record 
in a REGIONAL (1) data set even if it is not 
a dummy, similarly, during the sequential 
reading and printing of the contents of the 
data set, each record is tested and dummy 
records are not printed. 



REGIONAL (2) Data Sets 



The use of REGIONAL (2) data sets is 
illustrated in Figure 8-25, Figure 8-26, 
and Figure 8-27. The programs in these 
figures perform the same functions as those 
given for REGIONAL (3) , with which they can 
usefully be compared. 

The programs depict a library processing 
scheme, in which loans of books are 
recorded and reminders are issued for 
overdue books, two data sets, ST0CK2 and 
L0ANS2, are involved. ST0CK2 contains 
descriptions of the books in the library, 
and uses the U-digit book reference numbers 
as recorded keys; a simple algorithm is 
used to derive the region numbers from the 
reference numbers. (It is assumed that 
there are about 1000 books, each with a 
number in the range 1000-9999.) LOANS2 
contains records of books that are on loan; 
each record comprises two dates, the date 
of issue and the date of the last reminder. 
Each reader is identified by a 3- digit 
reference number, which is used as a region 
number in LOANS2; the reader and book 



numbers are concatenated to form the 
recorded keys. 

In Figure 8-25, the data sets ST0CK2 and 
LOANS 2 are created. The file LOANS, which 
is used to create the data set LOANS2 is 
opened for direct output merely tc format 
the data set; the file is closed 
immediately without any records being 
written onto the data set. It is assumed 
that the number of books on loan will not 
exceed 100; therefore the SPACE parameter 
in the DD statement that defines LOANS2 
requests 100 blocks of 19 bytes (12 bytes 
of data and a 7- byte key: see Figure 
8-26). Direct creation is also used for 
the data set STOCK2 because, even if the 
input data is presented in ascending 
reference number order, identical region 
numbers might be derived from successive 
reference numbers. 

Updating of the data set LOAN2 is 
illustrated in Figure 8-26. Each item of 
input data, read from a punched card, 
comprises a book number, a reader number, 
and a code to indicate whether it refers to 
a new issue (I), a returned book (R), or a 
renewal (A). The position cf the reader 
number on the card allows the 8-character 
region number to be derived directly by 
overlay defining. The DATE built-in 
function is used to obtain the current 
date. This date is written in both the 
issue date and reminder date portions of a 
new record or an updated record. 

The program in Figure 8-27 uses a 
sequential update file (LOANS) to process 
the records in the data set LOANS 2, and a 
direct input file (STOCK) tc obtain the 
book description from the data set STOCK2 
for use in a reminder note. Each record 
from L0AN2 is tested to see whether the 
last reminder was issued more than a month 
ago; if necessary, a reminder note is 
issued and the current date is written in 
the reminder date field of the record. 
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//OPT8#23 JOB 
//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
CRR1: PROC OPTIONS (MAIN) ; 

DCL NOS FILE RECORD OUTPUT DIRECT KEYED ENV (REGIONAL ( 1) ) , 
CARD CHAR (80), 

NAME CHAR(20) DEF CARD POS (1) , 
NUMBER CHAR (3) DEF CARD POS (21), 
IOFIELD CHAR (20) ; 

ON ENDFILE (SYSIN) GO TO FINISH; 



OPEN FILE(NOS); 
NEXT: GET FILE (SYSIN) 

IOFIELD=NAME; 

WRITE FILE (NOS) 

GO TO NEXT; 
FINISH: CLOSE FILE(NOS); 

END CRR1; 



EDIT (CARD) (A (80)); 

FROM (IOFIELD) KEYFROM (NUMBER) ; 



/* 

|//GO.NOS DD DSN=N0SA,UNIT=2311,SPACE= (TRK f (23,3)) ,DCB= (RECFM=F, 
// BLKSIZE=2 0,DSORG=DA) ,DISP= (NEW, KEEP) , V0L=SER=D186 

//GO. SYSIN DD * 

ACTI0N,G. 162 

BAKER, R. 152 

BRAMLEY,O.H. 248 

CHEESEMAN,L. 141 

CORY,G. 336 

ELLIOTT, D. 875 

FIGGINS,E.S. 413 

HARVEY, C.D.W. 205 

HASTINGS, G.M. 3 91 

KENDALL, J. G. 294 

LANCASTER, W.R. 624 

MILES, R. 233 

NEWMAN, M.W. 450 

PITT,W.H. 515 

ROLF.D.E. 114 

SHEERS, CD. 241 

SUTCLIFFE,M. 4 72 

TAYLOR, G. C. 407 

WILTON, L.W. 404 

WINSTONE,E.M. 307 
/* 

Figure 8-23. Creating a REGIONAL(l) data set 



REGIONAL (3) Data Sets 



The use of REGIONAL (3) data sets, 
illustrated in Figure 8-28, Figure 8-29, 
and Figure 8-30, is similar to the 
REGIONAL (2) figures, above; only the 
important differences are discussed here. 

To conserve space in the data set 
STOCK3, U-format records are used. In each 
record, the author's name and the title of 
the book are concatenated in a single 
character string, and the lengths of the 
two parts of the string are written as part 
of the record. The average record 
(including the recorded key) is assumed to 



be 60 bytes; therefore the average number 
of records per track (that is, per region) 
is 25, and there will be 40 regions. 

In Figure 8-28, the data set STOCK3 is 
created sequentially; duplicate region 
numbers are acceptable, because each region 
can contain more than one record. 

In Figure 8-29, the region number for 
the data set LOAN S3 is obtained simply by 
testing the reader number; there are only 
three regions, because a 2311 track can 
hold 36 nineteen-byte records. 

The only notable difference between 
Figure 8-30 and the corresponding 
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//OPT8#24 JOB 
//STEP1 EXEC PLIXCLG 

//PLI.SYSIN DD * 
ACRl: PROC OPTIONS (MAIN) ; 

DCL NOS FILE RECORD KEYED EN V (REGIONAL (1) ) , 
NAME CHAR(20), 
(NEWNO, OLDNO) CHAR (3), 
CODE CHAR(l), 
IOFIELD CHAR (20) , 
BYTE1 CHAR(l) DEF IOFIELD POS(l); 

ON ENDFILE(SYSIN) GO TO PRINT; 

OPEN FILE (NOS) DIRECT UPDATE; 
NEXT: GET FILE(SYSIN) EDIT (NAME, NEWNO f OLDNO f CODE) 

(A(20),2 A(3) ,X(53) f A(D) ; 
IF CODE^A' THEN GO TO RITE; 
ELSE IF CODE= , C' THEN DO; 
DELETE FILE (NOS) KEY (OLDNO); 
GO TO RITE; 
END; 
ELSE IF CODE= , D' THEN DELETE FILE (NOS) KEY (OLDNO); 
ELSE PUT FILE (SYSPRINT) SKIP 

EDIT( 'INVALID CODE: ' r NAME) (A (15) ,A) ; 
GO TO NEXT; 
RITE: READ FILE (NOS) KEY (NEWNO) INTO (IOFIELD) ; 

IF UNSPEC(BYTE1)=(8) , 1'B THEN WRITE FILE(NOS) KEY FROM (NEWNO) 

FROM (NAME); 
ELSE PUT FILE (SYSPRINT) SKIP EDIT (• DUPLICATE :• ,NAME) (A (15) , A) ; 
GO TO NEXT; 
PRINT: CLOSE FILE (NOS); 

PUT FILE (SYSPRINT) PAGE; 

OPEN FILE (NOS) SEQUENTIAL INPUT; 

ON ENDFILE(NOS) GO TO FINISH; 



NEXTIN: READ FILE (NOS) INTO (IOFIELD) KEYTO (NEWNO) ; 
IF UNSPEC(BYTE1)=(8) 'l'B THEN GO TO NEXTIN; 
ELSE PUT FILE (SYSPRINT) SKIP EDIT (NEWNO, IOFIELD) (A(5),A); 
GO TO NEXTIN; 
FINISH: CLOSE FILE (NOS) ; 
END ACR1; 
/* 

//GO. NOS DD DSN=N0SA,UNIT=2311,V0L=SER=D186,DISP= (OLD, KEEP* 
//GO.SYSIN DD * 

516450 C 

889 A 

233 D 

209 A 

183 A 

336 D 

001 A 

515 

114 D 

472875 C 

391 D 

439248 C 



NEWMAN, M. W 

GOODFELLOW,D.T. 

MILES,R. 

HARVEY, CD. W. 

BARTLETT,S.G. 

CORY,G. 

READ,K.M. 

PITT,W.H. 

ROLF,D.F. 

ELLIOTT, D. 

HASTINGS,G.M. 

BRAMLEY,O.H. 

/* 



Figure 8-24. Updating a REGIONAL (1) data set 
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//OPT8#25 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
CRR2: PROC OPTIONS (MAIN) ; 

DCL STOCK FILE RECORD KEYED ENV (REGIONAL (2) ) , 
LOANS FILE RECORD KEYED ENV ( REGIONAL ( 2 )) , 
NUMBER CHAR (4) , 
1 BOOK, 

2 AUTHOR CHAR (25) , 

2 TITLE CHAR (5 0) , 

2 QTY FIXED DEC (3) , 
INTER FIXED DEC (5), 
REGION CHAR (8) ; 

OPEN FILE (LOANS) DIRECT OUTPUT; 
CLOSE FILE(LOANS); 

ON ENDFILE(SYSIN) GO TO FINISH; 

OPEN FILE (STOCK) DIRECT OUTPUT; 
NEXT: GET FILE (SYS IN) LIST (NUMBER, BOOK) ; 

INTER=(NUMBER-1000)/9; /* INTERMEDIATE FIXED DECIMAL ITEM */ 
REGION=INTER; /* USED TO ENSURE CORRECT PRECISION */ 
WRITE FILE (STOCK) FROM (BOOK) KEYFROM ( NUMBER | | REGION) ; 
GO TO NEXT; 
FINISH: CLOSE FILE(STOCK); 
END CRR2; 

/* 

|//GO.LOANS DD DSN=LOANS2, UNIT=2311,SPACE=(19, 100) ,DCB= (RECFM=F, 
I // BLKSIZE=19 ,DSORG=DA,KEYLEN=7) ,DISP= (NEW,CATLG) , 

// VOLUME=SER=D186 

//GO. STOCK DD DSN=STOCK2, UNIT=2311, SPACE=(19, 100) ,DCB= (RECFM=F, 

// BLKSIZE=19 ,DSORG=DA,KEYLEN=7) ,DISP= (NEW,CATLG) , 

// V0LUME=SER=D186 

//GO. SYSIN DD * 

•1015' ' W.SHAKESPEARE' 'MUCH ADO ABOUT NOTHING* 1 

•1214' 'L. CARROLL* 'THE HUNTING OF THE SNARK' 1 

'3079* 'G. FLAUBERT" 'MADAME BOVARY" 1 

•3083' "V. M.HUGO' " LES MISERABLES ' 2 

•3085* ' J. K. JEROME' "THREE MEN IN A BOAT" 2 

•4295" "W.LANGLAND' 'THE BOOK CONCERNING PIERS THE PLOWMAN' 1 

'5999' ' O.KHAYYAM' 'THE RUBAIYAT OF OMAR KHAYYAM' 3 

•6591' 'F.RABELAIS' 'THE HEROIC DEEDS OF GARGANTUA AND PANTAGRUEL' 1 

'8362' 'H.D.THOREAU' 'WALDEN, OR LIFE IN THE WOODS' 1 

•9765' "H. G.WELLS' 'THE TIME MACHINE' 3 

/* 



Figure 8-25. Creating a REGIONAL (2) data set 



REGIONAL(2) figure is in the additional 
processing required for the anlysis of the 
records read from the data set STOCK3. The 
records are read into a varying- length 
character string and a based structure is 
overlaid on the string so that the data in 
the record can be extracted. 



TELEPROCESSING 



Teleprocessing in PL/I is provided by an 
extension of record- oriented transmission 



with the addition of the TRANSIENT file 
attribute and of the PENDING condition. 
The compiler provides a link between PL/ I 
message processing programs (MPPs) and the 
Telecommunications Access Method (TCAM) of 
the operating system. 

A TCAM message control program (MCP) 
handles messages originating from and 
destined for a number of remote terminals, 
each of which is identified by a terminal 
name carried with the message. These 
messages are transmitted to and from your 
PL/ I message processing program by means of 
queues in main storage. (These queues are 
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//OPT8#26 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
DUR2: PROC OPTIONS (MAIN) ; 
DCL 1 RECORD, 

2 (ISSUE, REMINDER) CHAR (6), 
SYSIN FILE RECORD INPUT SEQUENTIAL, 

LOANS FILE RECORD UPDATE DIRECT KEYED ENV (REGIONAL (2) ) , 
CARD CHAR(80), 
DATE BUILTIN, 

BOOK CHAR(4) DEF CARD POS (1) , 
READER CHAR (3) DEF CARD POS (10), 
CODE CHAR(l) DEF CARD POS (20), 
REGION CHAR (8) DEF CARD POS (5); 

ON ENDFILE (SYSIN) GO TO FINISH; 

OPEN FILE (SYSIN) ,FILE (LOANS); 
ISSUE, REM INDER=DATE; 
NEXT: READ FILE (SYSIN) INTO (CARD); 

IF CODE='I' THEN WRITE FILE(LOANS) FROM(RECORD) 

KEYFROM (READERJ | BOOK| (REGION) ; 
ELSE IF CODE= , R' THEN DELETE FILE (LOANS) 

KEY (READER | | BOOK | | REGION) ; 
ELSE IF CODE= , A' THEN REWRITE FILE (LOANS) FROM (RECORD) 

KEY (READER | |BOOK| | REGION) ; 
ELSE PUT FILE(SYSPRINT) SKIP LIST 

( ' INVALID CODE: ', BOOK , READER ) ; 
GO TO NEXT; 
FINISH: CLOSE FILE (SYSIN) , FILE (LOANS) ; 
END DUR2; 
/* 

//GO. LOANS DD DSN=LOANS2, DISP=OLD 
//GO. SYSIN DD * 



3085 


095 


X 


5999 


003 


A 


3083 


091 


R 


3083 


04 9 


I 


/* 







Figure 8-26. Updating a REGIONAL (2) data set directly 



supported by corresponding queues on a 
direct-access device in auxiliary storage. 
Your PL/I program has access only to the 
main storage queues by means of a single 
buffer for each file.) 



The exact message format (specified to 
the compiler by means of the ENVIRONMENT 
attribute) depends on the MPP. A message 
may be a complete unit, or may consist of a 
number of records so that it can be split 
up for processing. You must have this 
message format information to enable you to 
write the message processing program. Full 
information on how to write an MPP is given 
in the language reference manual for this 
compiler. A full account of TCAM procedure 
is given in the OS: TCAM Message processing 
Program Services and OS: TCAM Message 
Control Program publications. 



MESSAGE PROCESSING PROGRAM (MPP) 



This program receives the terminal iressage 
as input and produces output according to 
the data in the message. You can cede this 
program in PL/I. 

An MPP is not mandatory at 
teleprocessing installations, as for 
example, an MCP is. If the messages you 
transmit do not require processing, because 
they are only switched between terminals, 
an MPP is not required. However, ycu can 
pass data to a problem program and you can 
receive the output with a mininruro of delay, 
and roost installations are likely to have a 
set of processing prograirs available for 
these purposes. These programs are stored 
as load modules, either in main storage or 
in a library in auxiliary storage. 
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//OPT8#27 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
SUR2: PROC OPTIONS (MAIN) ; 

DCL LOANS FILE RECORD SEQUENTIAL UPDATE KEYED ENV (REGIONAL (2) ) , 
STOCK FILE RECORD DIRECT INPUT KEYED ENV (REGIONAK2) ) , 
(TODAY, LAS MTH) CHAR(6), 
YEAR PIC '99' DEF LASMTH, 
MONTH PIC '99' DEF LASMTH POS(3), 
1 RECORD, 

2 (ISSUE, REMINDER) CHAR (6), 
DATE BUILT IN, 
LOANKEY CHAR (7 ) , 

READER CHAR (3) DEF LOANKEY POS(l), 
BKNO CHAR (4) DEF LOANKEY POS (4) , 
INTER FIXED DEC (5), 
REGION CHAR (8) , 
1 BOOK, 

2 AUTHOR CHAR (25), 

2 TITLE CHAR (50) , 

2 QTY FIXED DEC (3 ) ; 

TODAY , LASMTH=DATE; 
IF MONTH =« 01' THEN DC- 
MONTH^' 12' ; 
YEAR=YEAR-1; 
END; 
ELSE MONTH=MONTH-l; 
OPEN FILE (LOANS), FILE (STOCKT- 
ON ENDFILE (LOANS) GO TO FINISH; 

NEXT: READ FILE (LOANS) INTO (RECORD) KEYTO (LOANKEY) ; 

IF REMINDER<LASMTH THEN DO; 
REMINDER=TODAY ; 

REWRITE FILE (LOANS) FROM (RECORD) ; 

INTER= (BKNO- 1000) /9; /* INTERMEDIATE FIXED DECIMAL ITEM */ 
REGION=INTER; /* USED TO ENSURE CORRECT PRECISION */ 
READ FILE(STOCK) INTO(BOOK) KEY (BKNO | | REGION) ; 
PUT FILE (SYS PRINT) SKIP (4) EDIT (READER, AUTHOR, TITLE) 
(A, SKIP (2)); 
END; 
GO TO NEXT; 
FINISH: CLOSE FILE (LOANS) , FILE (STOCK) ; 
END SUR2; 
/* 

//GO. LOANS DD DSN=LOADS2 ,DlSP=OLD 
//GO. STOCK DD DSN=STOCK2, DISP=OLD 

Figure 8-27. Updating a REGIONAL (2) data set sequentially 



HOW TO RUN AN MPP 



An example of an MPP and the job control 
language required to create it is shown in 
Figure 8-31. The EXEC statement invokes 
the cataloged procedure PLIXCL to compile 
and link edit the PL/I message processing 
program. The appropriate TCAM modules are 
included in the program by the linkage 
editor. The load module produced is stored 
in the partitioned data set SYSl.MSGLIB 
under the member name MPPROC. 



MPP is declared as a teleprocessing file 
that can process messages up to 100 bytes 
long, similarly OUTMSG is declared as a 
teleprocessing file that can receive 
messages up to 500 bytes long. 

The READ statement gets a record (that 
is, a message) from the queue. The 
terminal identifier is inserted into the 
KEYTO character string. The record is 
placed in the INDATA variable for 
processing. The appropriate READ SET 
statement could also have been used here. 
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//OPT8#28 JOB 
//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 
CRR3: PROC OPTIONS (MAIN) ; 

DCL STOCK FILE RECORD KEYED ENV (REGIONAL ( 3) ) , 
1 CARD, 

2 NUMBER CHAR (4 ) , 

2 AUTHOR CHAR (25) VAR, 

2 TITLE CHAR (5 0) VAR, 

2 QTY1 FIXED DEC ( 3) , 
(L1,L2,X) FIXED DEC (3), 
1 BOOK CTL, 

2 (L3,L4) FIXED DEC (3 ) , 

2 QTY2 FIXED DEC (3) , 

2 DESCN CHAR(X) VAR, 
INTER FIXED DEC (5) , 
REGION CHAR (8); 

ON ENDFILE(SYSIN) GO TO FINISH; 

OPEN FILE (STOCK) SEQUENTIAL OUTPUT; 

GET FILE(SYSIN) LIST (CARD) ; 

L1=LENGTH (AUTHOR) ; 

L2=LENGTH (TITLE) ; 

X=L1+L2; 

ALLOCATE BOOK; 

L3=L1; 

L4=L2; 

QTY2=QTY1; 

DESC N=AUTHOR | | TITLE ; 

INTER- (NUMBER-1 000 )/225; 

REGION= INTER; 



NEXT: 



/* INTERMEDIATE FIXED DECIMAL */ 

/* ITEM USED TO ENSURE CORRECT PRECISION 



*/ 



FINISH: 



WRITE FI LE (STOCK) FROM (BOOK) KEYFROM (NUMBER | |REGION) ; 

FREE BOOK; 

GO TO NEXT; 

CLOSE FILE(STOCK); 

END CRR3; 



/* 

|//GO. STOCK DD DSN=STOCK3 ,UNIT=2311 ,SPACE= (TRK , (40, 5) ) , DCB= (RECFM=U, 
// BLKSIZE=110,DSORG=DA,KEYLEN=4) ,DISP= ( , CATLG) ,V0L=SER=D18 6 

//GO. SYS IN DD * 

'1015' 'W.SHAKESPEARE' 'MUCH ADO ABOUT NOTHING' 1 

'1214' 'L. CARROLL' 'THE HUNTING OF THE SNARK ' 1 

'3079' 'G.FLAUBERT* 'MADAME BOVARY' 1 

•3083' ' V.M.HUGO' « LES MISERABLES ' 2 

•3 085' 'J. K.JEROME' 'THREE MEN IN A BOAT' 2 

'4295' 'W.LANGLAND' 'THE BOOK CONCERNING PIERS THE PLOWMAN' 1 

•5999' ' O.KHAYYAM' 'THE RUBAIYAT OF OMAR KHAYYAM' 3 

•6591' ' F.RABELAIS* 'THE HEROIC DEEDS OF GARGANTUA AND PANTAGRUEL * 1 

'8362' 'H.D.THOREAU' 'WALDEN, OR LIFE IN THE WOODS' 1 

•9765* 'H.G.WELLS* 'THE TIME MACHINE' 3 
/* 

Figure 8-28. Creating a REGIONAL (3) data set 
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//OPT8#29 JOB 
//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
DUR3: PROC OPTIONS (MAIN) ; 

DCL 1 RECORD, 

2 (ISSUE, REMINDER) CHAR(6), 
SYSIN FILE RECORD INPUT SEQUENTIAL, 

LOANS FILE RECORD UPDATE DIRECT KEYED ENV (REGIONAL (3 )) , 
CARD CHAR(80), 

BOOK CHAR (4) DEF CARD POS(l) , 
READER CHAR (3) DEF CARD POS(IO), 
CODE CHAR(l) DEF CARD POS(20), 
DATE BUILTIN, 
REGION CHAR (8) ; 

ON ENDFILE (SYSIN) GO TO FINISH; 

OPEN FILE (SYSIN) ,FILE (LOANS ) ; 
ISSUE, REM INDER= DATE ; 
NEXT: READ FILE (SYSIN) INTO (CARD); 

IF READER< , 034 i THEN REGION= • 00000000 • ; 
ELSE IF READER< , 067' THEN REGION= f 00000001' ; 

ELSE REGION=' 00000002* ; 
IF CODE='I' THEN WRITE FILE(LOANS) FROM(RECORD) 

KEYFROM (READER | | BOOK | | REGION) ; 
ELSE IF CODE='R' THEN DELETE FILE (LOANS) 

KEY (READER | |BOOK| | REGION) ; 
ELSE IF CODE= , A' THEN REWRITE FILE (LOANS) FROM (RECORD) 
KEY(READER| | BOOK | | REGION) ; 
ELSE PUT FILE(SYSPRINT) SKIP LIST 

( ' INVALID CODE * , BOOK , READER) ; 
GO TO NEXT; 
FINISH: CLOSE FILE (SYSIN) , FILE (LOANS) ; 
END DUR3; 
/* 

//GO. LOANS DD DSN=LOANS3, DISP=OLD 
//GO. SYSIN DD * 
3085 095 X 

5999 003 A 

3083 091 R 

3083 049 I 

/* 

Figure 8-29. Updating a REGIONAL (3) data set directly 
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//OFT8#30 JOB 
//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 
SUR3: PROC OPTIONS (MAIN) ; 

DCL LOANS FILE RECORD SEQUENTIAL UPDATE KEYED ENV (REGIONAL (3) ) , 
STOCK FILE RECORD DIRECT INPUT KEYED ENV (REGIONAK 3) ) , 
(TODAY, LASMTH) CHAR( 6) , 
YEAR PIC »99' DEF LASMTH, 
MONTH PIC • 99« DEF LASMTH POS(3), 
1 RECORD, 

2 (ISSUE, REMINDER) CHAR (6 ) , 
LOANKEY CHAR ( 7) , 

READER CHAR(3) DEF LOANKEY POS (1) , 
BKNO CHAR (4) DEF LOANKEY POS ( 4) , 
INTER FIXED DEC (5), 
DATE BUILTIN, 
REGION CHAR (8) , 
1 BOOK, 

2 (L1,L2) FIXED DEC (3 ) , 

2 QTY FIXED DEC(3), 

2 DESCN CHAR(75)VAR, 
AUTHOR CHAR (25) VAR, 
TITLE CHAR (50) VAR; 

TODAY, LASMTH =DATE; 

IF MONTH= , 01» THEN DO; 

MONTH='12' ; 

YEAR=YEAR-1; 

END; 
ELSE MONTH=MONTH-l; 
OPEN FILE (LOANS), FILE (STOCK); 

ON ENDFILE (LOANS) GO TO FINISH; 

NEXT: READ FILE (LOANS) INTO (RECORD) KEYTO ( LOANKEY) ; 
IF REMINDER<LASMTH THEN DO; 
REM INDER=TO DAY ; 

REWRITE FILE (LOANS) FROM (RECORD) ; 

INTER=(BKNO-1000)/225; /* INTERMEDIATE FIXED DECIMAL */ 

REGION=INTER; /*ITEM USED TO ENSURE CORRECT PRECISION */ 

READ FILE(STOCK) INTO(BOOK) KEY (BKNO | | REGION) ; 
AUTHOR=SUBSTR (DESCN ,1, LI) ; 
TITLE=SUBSTR ( DESCN, Ll+ 1 , L2 ) ; 
PUT FILE(SYSPRINT) SKIP (4) EDIT (READER, AUTHOR, TITLE) 

(A,SKIP(2)); 
END; 
GO TO NEXT; 
FINISH: CLOSE FILE (LOANS) , FILE (STOCK) ; 
END SUR3; 
/* 

//GO. LOANS DD DSN=LOANS3, DISP=OLD 
//GO. STOCK DD DSN=STOCK3 ,DISP=OLD 

Figure 8-30. Updating a REGIONAL (3) data set sequentially 
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// JOB 

// EXEC PLIXCL 

//PLI.SYSIN DD * 

MPPROC : PROC OPTI ONS ( MAI N ) ; 

DCL MPP FILE RECORD KEYED TRANSIENT ENV (TP(M) RECSIZE (100) ) f 

OUTMSG FILE RECORD KEYED TRANSIENT ENV (TP (M)RECSIZE( 500) ) , 

INDATA CHAR (100) , 

OUTDATA CHAR (500) , 

TKEY CHAR (6); 



OPEN FILE (MPP) INPUT, FILE (OUTMSG) OUTPUT; 



READ FILE (MPP) KEYTO(TKEY) INTO (INDATA) j ; 



WRITE FILE (OUTMSG) KEYFROM (TKEY) FROM (OUTDATA) ; 



ENDTP: CLOSE FILE (MPP) , FILE (OUTMSG) ; 
END MPPROC; 

[/* 

| //LKED. SYSLMOD DD DSNAME=SYS1. MSGLIB (MPPROC) r . . . 
Figure 8-31. PL/I message processing program 

The WRITE statement puts the data in The JOBLIB DD statement is required to 

OUTDATA into the destination queue; the make SYS1.MSGLIB available sc that the 

terminal identifier is taken from the operating system can find the prograir 

character string in TKEY. An appropriate MPPROC. The DD statement with the name DD1 

LOCATE statement could also have been used. associates the FL/I file with the irain 

storage queue name (MPP). 

Once the load module has been stored on 
a direct-access device it can be restored 
for execution at any time. The job control 
statements to perform this might be: 

// JOB 

//JOBLIB DD DSNAME=SYSl.MSGLIB,DISP=SHR 

// EXEC PGM=MPPROC 

//MPP DD QNAME= . . . 

//OUTMSG DD QNAME=... 

//SYSPRINT DD SYSOUT=A 
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Chapter 9: Virtual Storage Access Method(VSAM) 



The virtual Storage Access Method (VSAM) is 
both an access method and a form of data 
set organization. VSAM is available only 
to System/370 users. A virtual storage (or 
relocate) version of the operating system 
is required. 

VSAM data sets can reside only on the 
following direct access storage devices: 

IBM 2305 
IBM 2314 
IBM 2319 
IBM 333 
IBM 3340 



VSAM Data Sets 



There are two types of VSAM data sets: 
entry sequenced data sets (ESDS) and key 
sequenced data sets (KSDS) . Key sequenced 
data sets have an associated index; a KSDS 
together with its index is referred to as 
an indexed VSAM data set. An entry 
sequenced data set has no associated index. 

All VSAM data sets are cataloged, either 
in a master catalog or in a user catalog. 
The catalog entry is made when the data set 
is "defined", and remains until the data 
set is "deleted". 



DATA FORMAT 



The unit of data that is transmitted 
between a PL/ I program and a VSAM data set 
is called a logical record . Logical 
records have no defined record format; VSAM 
will accept records of any length up to a 
maximum value that is specified when the 
data set is defined. 

Logical records are grouped together in 
control intervals , and control intervals in 
turn are grouped in control areas . The 
sizes of control intervals and control 
areas are selected by the system to make 
optimum use of the particular storage 
device that is being used. 



KEY SEQUENCED DATA SETS 



Figure 9-1 illustrates the structure of a 



key acyuenced data set. Each control 
interval contains system control 
information, one or more logical records, 
and some free space to allow for the later 
addition of records. The amount of free 
space in a control interval can be 
specified as a percentage of the total 
space when the data set is defined (see 
"Creating VSAM Data sets" later in this 
chapter). Similarly, the user can specify 
how many empty control intervals are to be 
left in each control area to allow for 
future additions. 

Logical records in a KSDS are ordered in 
the collating sequence of an embedded key. 
The order is maintained when records are 
inserted into an existing data set, and 
when existing records are increased or 
decreased in length. Deleted records are 
physically deleted from the data set. The 
free space specification facility iirproves 
the performance of update operations by 
minimizing the moving of records and the 
splitting of control intervals and areas 
when records are added or increased in 
length. 



Associated with each KSDS is an index 
data set. The index is in the form of a 
tree structure that gives rapid access to a 
specified key value. The lowest level of 
the index data set is known as the 
"sequence set", and the remaining levels 
are known as the "index set". For direct 
access, a logical record with a particular 
key is located by means of a search through 
successive levels of the index data set. 
This process is illustrated in Figure 9-2. 
For sequential access,, only the sequence 
set is used. 



ENTRY SEQUENCED DATA SETS 



The structure of an entry sequenced data 
set is similar to that of a key sequenced 
data set in that it contains logical 
records within control intervals within 
control areas. However, the logical 
records are stored in the order in which 
they are submitted when the data set is 
created, and records cannot be subsequently 
added (except at the end of the data set), 
deleted, or changed in length. Any unused 
space which exists in a control interval is 
thus wasted space. 
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CONTROL AREA 



CONTROL INTERVAL 
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LR = logical record 

FS - free space 

SC = system control information 

Figure SI-jL. Structure of Key Sequenced Data Set 
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Figure 9-2. Indexed VSAM Data Set 
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Operations on VSAM Data Sets 



ACCESS METHOD SERVICES 



Access Method services is a utility program 
that enables various operations to be 
performed on VSAM data sets. It is used to 
define VSAM data sets, to delete their, to 
print out their contents, and so on. A 
full description of the use and syntax of 
access method services is given in OS/VS 
Access Method Services , Order No. GC35- 
0009. The principal functions are listed 
in Figure 9-3. 



DEFINE To create VSAM catalogs and data 
set entries within the VSAM 
catalogs. 

ALTER To change VSAM catalog entries. 

DELETE To remove entries from the VSAM 
catalog. 

LISTCAT To list entries within VSAM 
catalogs. 

REPRO To copy the contents of data sets 
into other data sets. 

PRINT To print the contents of data 
sets . 

EXPORT To produce backup or portable 
copies of VSAM data sets. 

IMPORT To accept backup or portable 
copies of VSAM data sets. 

VERIFY To check the end-of-file 

information in a catalog for 
correspondence to the physical end 
of the data set. 

Figure 9-3. The principal Access 

Method Services functions 



CREATING VSAM DATA SETS 



Before a VSAM data set can be created, VSAM 
data space must be available on a suitable 
direct access storage device. Space can be 
obtained by using the DEFINE command of 
Access Method services; this space is then 
owned by VSAM and is used as a space pool 
for the creation of VSAM data sets. 

When VSAM data space is available, the 
characteristics of the VSAM data set that 
is to be created are defined by means of a 



further DEFINE command. This causes an 
entry for the VSAM data set to be made in 
the VSAM master catalog, and the space 
requested for the data set to be obtained 
from the available VSAM space and 
formatted. The data set can then be 
"loaded" with data by the application 
program. 

The use of the DEFINE command for these 
purposes is illustrated in the examples 
later in this chapter. 

Note ; The DEFINE command for the data 
set may specify either SUBALLOCATION or 
UNIQUE. SUBALLOCATION, which is the 
standard default, specifies that the space 
for the data set is to be a suballocation 
of VSAM space on a specified volume. If 
UNIQUE is specified, the allocation is made 
directly on a specified voluire, and it is 
not necessary to obtain VSAM space as 
described in the preceeding paragraphs. In 
the rest of this chapter it is assumed that 
SUBALLOCATION is in effect. 



Creating a Key Sequenced Data Set 



The example in Figure 9-4 illustrates the 
creation of a key sequenced data set. This 
example is similar to that shown in Chapter 
8 for the creation of an INDEXED data set; 
the only changes in the PL/I program are 
the replacement of INDEXED by VSAM in the 
ENVIRONMENT option of the output file 
declaration, and a modification to the 
output record structure so that the records 
contain embedded keys. 

The first job step invokes Access Method 
Services (PGM=IDCAMS) to obtain space for 
the data set and to enter its 
characteristics in the VSAM catalog. The 
first DEFINE command obtains VSAM data 
space on volume HUR137. Note that the FILE 
parameter in this DEFINE statement refers 
to the DD statement with the ddname DDL 
This DEFINE command and the corresponding 
DD statement may be omitted if sufficient 
VSAM space is already available on the 
required volume. 

The second DEFINE statement defines the 
VSAM "cluster" that contains the data set 
and its associated index data set. It 
specifies that the data set and its index 
are to be placed on volume HUR137 and that 
the name of the data set (the dsname) is 
TELNO. The definition of the data set 
includes the information that the embedded 
key is 20 characters long and is at the 
front of the logical records, that both the 
average and the maximum lengths of logical 
records are 23 bytes, that 20% of the space 
in each control interval is to be left 



Chapter 9: Virtual Storage Access Method (VSAM) 133 



//OPT9#4 JOB 

// EXEC PGM=IDCAMS 

//SYS PRINT DD SYSOUT=A 

//DD1 DD UNIT=2314,VOL=SER=HURl37,DISP=OLD 

//SYS IN DD * 

DEFINE SPACE(V0L(HUR137) FILE(DDl) CYL(10 f 10)) 
DEFINE CLUSTER (NAME (TELNO) VOL(HURl37)) 

DATA(CYL(4,1) KEYS (20,0) RECSZ (23,23) 

FREESPACE(20,30)) - 
INDEX (CYL (1,1)) 
/* 

// EXEC TL1LOCLG 
//PLI.SYSIN DD * 
TELNOS: PROC OPTI ONS (MAI N) ; 

DCL DIREC FILE RECORD SEQUENTIAL KEYED ENV(VSAM) 
CARD CHAR (80) , 

NAME CHAR(20) DEF CARD POS(l), 
NUMBER CHAR (3) DEF CARD POS(21), 
OUTREC CHAR(23) DEF CARD POS(l); 

ON ENDFILE(SYSIN) GOTO FINISH; 

OPEN FILE (DIREC) OUTPUT; 

NEXTIN:GET FILE(SYSIN) EDIT (CARD) (A(80)); 

WRITE FILE (DIREC) FROM (OUTREC) KEYFROM ( NAME ) ; 
GOTO NEXTIN; 

FINISH:CL0SE FILE(DIREC); 

END TELNOS; 
//GO. DIREC DD DSNAME=TELNO, DISP=OLD 



//GO. SYS IN DD * 




ACTION, G. 


162 


BAKER, R. 


152 


BRAMLEY,O.H. 


248 


CHEESEMAN,D. 


141 


CORY,G. 


336 


ELLIOTT, D. 


875 


FIGGINS,S. 


413 


HARVEY, CD. W. 


205 


HASTINGS, G.M. 


3 91 


KENDALL, J. G. 


294 


LANCASTER, W.R. 


624 


MILES, R. 


233 


NEWMAN, M. W. 


450 


PITT,W.H. 


515 


ROLF,D.E. 


114 


SHEERS, CD. 


241 


SUTCLIFFE,M. 


472 


TAYLOR, G.C 


407 


WILTON, L. W. 


4 04 


WINSTONE,E.M. 


307 


/* 




Figure 9-4. Creating a: 



Creating and Initializing a Key Sequenced Data Set 
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//OPT9#5 JOB 
//STEP1 EXEC TL1LOCLG 
//PLI.SYSIN DD * 
DIRUPDT: PROC OPTIONS (MAIN) ; 

DCL DIREC FILE RECORD KEYED ENV(VSAM), 
ONCODE BUILTIN, 
OUTREC CHAR (23), 

NUMBER CHAR (3) DEF OUTREC POS(21), 
NAME CHAR(20) DEF OUTREC, 
CODE CHAR (2) ; 

ON ENDFILE(SYSIN) GO TO PRINT; 

ON KEY(DIREC) BEGIN? 
IF ONCODE=51 THEN PUT FILE (SYSPRINT) SKIP EDIT 
('NOT FOUND:' , NAME) (A (15), A); 
IF ONCODE=52 THEN PUT FILE ( SYSPRINT) SKIP EDIT 
('DUPLICATE:' , NAME) (A(15), A); 
END; 

OPEN FILE (DIREC) DIRECT UPDATE; 

NEXT: GET FILE(SYSIN) EDIT ( NAME, NUMBER, CODE) (A(20) ,A (3) ,X (56) ,A (1) ) ; 

IF CODE='A' THEN WRITE FILE (DIREC) FROM(OUTREC) KEYFROM (NAME) ; 
ELSE IF CODE='C THEN REWRITE FILE (DIREC) FROM (OUTREC) 

KEY (NAME); 
ELSE IF CODE='D' THEN DELETE FILE(DIREC) KEY (NAME) ; 
ELSE PUT FILE( SYSPRINT) SKIP EDIT ( 'INVALID CODE: ', NAME) 

(A (15), A); 
GO TO NEXT; 

PRINT: CLOSE FILE (DIREC) ; 

PUT FILE (SYSPRINT) PAGE; 

OPEN FILE (DIREC) SEQUENTIAL INPUT; 

ON ENDFILE( DIREC) GO TO FINISH; 

NEXTIN: READ FILE( DIREC) INTO(OUTREC ) ; 

PUT FILE (SYSPRINT) SKIP EDIT (OUTREC) (A) ; 
GO TO NEXTIN; 
FINISH: CLOSE FILE (DIREC) ; 
END DIRUPDT; 
/* 

//GO. DIREC DD DSNAME=TELNO, DISP=OLD 
//GO.SYSIN DD * 

C 
A 
D 
A 
A 
E 
A 

D 
C 
D 
C 



NEWMAN, M.W. 




516 


GOODFELLOW,D. 


T. 


889 


MILES, R. 






HARVEY, C.D.W. 




209 


BARTLETT,S.G. 




183 


CORY,G. 






READ,K.M. 




001 


PITT,W.H. 






ROLF,D.F. 






ELLIOTT, D. 




291 


HASTINGS,G.M. 






BRAMLEY,O.H. 




439 


/* 






Figure 9-5. 


Updating a 
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//OPT9#6 JOB 
// EXEC PGM=IDCAMS 

//SYS PRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE CLUSTER ( NAME (DS 3) V0L(HUR137) CYL(1,1) RECSZ (80,80) 
NONINDEXED) 
/* 

//STEP1 EXEC TL1LOCLG 
//PLI.SYSIN DD * 
MERGE : PROC OPTI ONS ( MAI N ) ; 

DCL (INl r IN2) FILE RECORD SEQUENTIAL, 

OUT FILE RECORD SEQUENTIAL ENV(VSAM), 
(ITEM1 BASED (A), ITEM 2 BASED(B)) CHAR (80); 
ON ENDFILE(INl) BEGIN; 
ON ENDFILE(IN2) GO TO FINISH; 
NEXT 2: WRITE FILE (OUT) FROM (ITEM 2); 

READ FILE(IN2) SET(B); 
GO TO NEXT 2; 
END; 

ON ENDFILE(IN2) BEGIN; 
ON ENDFILE(INl) GO TO FINISH; 
NEXT1: WRITE FILE (OUT) FROM (ITEM1) ; 

READ FILE(INl) SET (A) ; 
GO TO NEXTl; 
END; 

OPEN FILE (INI) INPUT, 
FILE(IN2) INPUT, 
FILE (OUT) OUTPUT; 
READ FILE(INl) SET (A); 
READ FILE (IN 2) SET(B); 
NEXT: IF ITEML>ITEM2 THEN DC- 

WRITE FILE (OUT) FROM(ITEM2) ; 
READ FILE(IN2) SET(B); 
GO TO NEXT; 
END; 

ELSE DO; 
WRITE FILE (OUT) FROM(ITEMl); 
READ FILE (INI) SET (A) ; 
GO TO NEXT; 
END; 
FINISH: CLOSE FILE (INI ), FILE (IN2 ), FILE (OUT) ; 

END MERGE; 
/* 

//GO. OUT DD DSNAME=DS3,DISP=OLD 
//GO. INI DD * 

(insert here data to be included in the input stream) 
//GO. IN2 DD * 

(insert here data to be included in the input stream) 
/* 



Figure 9-6. Creating an Entry Sequenced Data Set 



free, and that 3 0% of the control intervals Accessing a Key Sequenced Data Set 



in each control area are also to be 
free. 



left 



The following job steps compile, link-edit, 
and execute the PL/ I program that loads the 
initial information into the data set. 
Note that the only information that need be 
supplied in the DD statement for the data 
set is the data set name that was defined 
in the DEFINE statement, together with the 
data set disposition (DISP=) . 



The program in Figure 9-5 updates the data 
set that was created in Figure 9-4 and 
prints out its new contents. This example 
is similar to that shown in Chapter 8 for 
updating an INDEXED data set. 
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Creating and Accessing an Entry 
Seguenced Data Set 



The example in Figure 9-6 illustrates the 
creation of an entry sequenced data set. 
The example is similar to that given in 
Chapter 8 for the creation of a CONSECUTIVE 
data set. 

The first job step in the example 
invokes Access Method services to define 
and catalog the data set. It is assumed in 
this example that VSAM already "owns" data 
space on the specified volume. Note that 
the VSAM "cluster" in this case contains 
only the ESDS. NONINDEXED must be 
specified in the DEFINE statement, to 
indicate that the records contain no keys 
and that an ESDS is required. 

The PL/ I program in this example merges 
the contents of two existing data sets, DSl 
and DS2, and writes them onto the VSAM data 
set defined in the previous job step. Each 
of the original data sets contains 80- byte 
fixed length records arranged in EBCDIC 
collating sequence. 



DD Statements for VSAM Data Sets 



This section describes the minimum 
information that must appear in DD 
statements for VSAM data sets. The 
additional facilities that are available 
through the job control language are also 
listed; further information on these 
facilities is given in OS/VS VSAM 
Programmer's Guide , Order No. GC26-38 06. 

If a DEFINE command is used to obtain 
VSAM data space on a particular volume, a 
DD statement must be provided to define the 
volume. The ddname of this DD statement 
must appear in the FILE parameter of the 
DEFINE command. The DD statement must 
contain the UNIT, VOLUME, and DISP 
parameters. For example, if the DEFINE 
command is: 

DEFINE SPACE (.... FILE(DDN) ) 

the corresponding DD statement roust have 
the form: 

//DDN DD UNIT=XXXX,VOL=SER=yyyy,DISP=OLD 

Once a data set has been defined using 
the DEFINE command, it can be accessed by 
specifying the dsname and a disposition of 
OLD. Additional parameters can, however, 
be specified. For VSAM data sets, the DCB 
parameter is invalid; its place is taken by 
the AMP parameter. The AMP parameter has 
the following format: 



AMP- • subparameter , subparaireter , . . . • 

The valid subparameters cf the AMP 
parameter are: 



BUFSP=number 

BUFND=number 
BUFNI=number 
RECFM=format 



STRNO= number 



TRACE 



AMORG 



| OPTCD= {L | IL } 



specifies the amount of 
storage to be set aside 
for VSAM buffers. 

specifies the number of 
data buffers required. 

specifies the number of 
index buffers required. 

specifies record fcrroat. 
The use of this 
subparaireter is described 
under the heading "The 
Compatibility Interface" 
later in this chapter. 

specifies how many 
concurrent data-set 
positioning requests VSAM 
must be prepared tc 
handle. For convenience, 
the PL/I programmer can 
make STRNO equal to the 
number of PL/I files that 
will be open on the data 
set at the same time. 

specifies that a trace of 
Access Method Control 
Blocks (ACEs) is required 
during processing. 

must be specified if 
VOL=SER information is 
used to define a catalog 
or a subset mount of a 
multivolume data set. 

specifies how deleted 
records are to be handled 
when the ccmpatibility 
interface is being used 
(see "The ccmpatibility 
Interface" later in this 
chapter. ) 



The Compatibility Interface 



PL/ I programs that are written to create 
and access ISAM data sets (ENV (INDEXED) ) 
can be used to access VSAM key sequenced 
data sets without alteration. Two types of 
access are possible: "native" access, in 
which the data set is accessed exactly as 
though the file had been declared with 
ENV (VSAM), and access via the ISAM/VSAM 
compatibility interface. 

The fact that the data set being 
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accessed is a VSAM data set is detected by 
the PL/I library routines when the file is 
opened, and the required support is 
provided. This support will normally be 
native VSAM support; in order to force use 
of the compatibility interface, the user 
must code either RECFM=F| FB| V| VB or OPTCD=L 
in the AMP parameter of the DD statement 
for the data set. Use of the compatibility 
interface must be forced if any of the 
following situations exists: 

• The PL/I program uses records with non- 
embedded keys. 

The user requires the lengths of records 
being read or written to be checked 
against the record length specified for 
the data set; the RECORD condition is to 
be raised if an incorrect-length record 
is encountered. 



programmer: 
1 



Master Password - Specifying this 
password allows the user to perform 
any operation on a data set cr en the 
index and catalog records associated 
with it. 



2. Update Password - Specifying this 
password allows the user to retrieve, 
update, delete, or insert records in a 
data set. 

3. Read-only Password - Specifying this 
password allows the user to retrieve 
records form a data set, but not to 
update, delete, or insert records. 

Note that password protection is 
effective only if the catalog that contains 
the data set is itself password protected. 



Deleted records are to be retained in 
the data set (ISAM deletion). If 
deleted records are to be deleted from 
the data set (VSAM deletion), but the 
compatibility interface must be used for 
some other reason, the programmer must 
specify OPTCD=IL. 



Sharing VSAM Data Sets 



SHARING BETWEEN JOBS 



• The number of channel programs specified 
(NCP) is greater than one. Note, 
however, that the compatibility 
interface is obtained automatically in 
this case if a file declared with 
ENV(INDEXED) is opened on a VSAM KSDS. 

If the compatibility interface is used, 
and RECFM is not specified either in the 
program or in the AMP parameter, the 
default is RECFM=V. 

If a PL/ I file declared with 
ENV( INDEXED) is used to load a VSAM KSDS 
with F-format records, and the key is not 
embedded, the record size specified on the 
DEFINE command for the VSAM data set must 
be equal to the length of the user record 
plus the length of the key. 



Password Protection of VSAM Data Sets 



VSAM provides a password protection option 
that enables VSAM data sets to be protected 
against unauthorized access or deletion. 
Passwords are specified as a parameter of 
the DEFINE command when a VSAM data set is 
defined. In order to gain access to a 
password- protected data set, the PL/I 
programmer must specify the correct 
password in the the ENVIRONMENT attribute 
of the PL/I file. 

There are three levels of password 
protection of interest to the PL/I 



Independent jobs running in the same system 
may share VSAM data sets provided that both 
jobs specify DISP=SHR in their DD 
statements for the data set. The type of 
sharing that is to be allowed on any 
particular data set can be specifed in the 
DEFINE command when the data set is 
defined. The following four types cf 
sharing are possible: 

1. The data set may be used by one job 
for output or by any nuirber of jobs 
for input. 

2. The data set may be used by one job 
for output and by any number of jobs 
for input. 

3. The data set may be fully shared, the 
user being completely responsible for 
read and write integrity. 

4. As (3) above, but VSAM will refresh 
the buffers for each request. 



SHARING BETWEEN SUBTASKS IN A JOB 



Subtasks can share VSAM data sets either 
through separate DD statements or through 
the same DD statement. 

If separate DD statements are used, the 
rules are the same as those for sharing 
between jobs. 
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If a single DD statement is used, the 
data set can be fully shared. The value of 
STRNO specified in the AMP parameter of the 
DD statement should be equal to the number 
of files that will be open on the data set 
concurrently. 
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Chapter 10: Libraries of Data Sets 



Within the IBM operating system, the terras 
"partitioned data set" and "library" are 
used synonymously to signify a type of data 
set that can be used for the storage of 
other data sets (usually programs in the 
form of source, object or load modules). A 
library must be stored on direct- access 
storage and be wholly contained in one 
volume. It contains independent, 
consecutively-organized, data sets, called 
members. Each member has a unique name, 
not more than eight characters long, which 
is stored in a directory that is part of 
the library. All the members of one 
library must have the same data 
characteristics because only one data set 
label is maintained. 

Members can be created individually 
until there is insufficient space left for 
a new entry in the directory, or until 
there is insufficient space for the member 
itself. Members can be accessed 
individually by specifying the member name. 

DD statements or ALLOCATE commands are 
used to create and access members. 

Members can be deleted by means of the 
IBM utility program IEHPROGM. This deletes 
the member name from the directory so that 
the member can no longer be accessed; but 
the space occupied by the member itself 
cannot be used again unless the library is 
recreated using, for example, the IBM 
utility program IEBCOPY. An attempt to 
delete a member by using the DISP parameter 
of a DD statement will cause the whole data 
set to be deleted. 



Types of Library 

The following types of library may be used 
with a PL/ I program: 

• The system program library 
SYSl.LINKLIB. This can contain all 
system processing programs such as 
compilers and the linkage editor. 

• Private program libraries. These 
usually contain user-written programs. 
It is often convenient to create a 
temporary private library to store the 
load module output from the linkage 
editor until it is executed by a later- 
job step in the same job. The library 
will be deleted at the end of the job. 
Private libraries are also used for 



automatic library call by the linkage 
editor and the loader. 

The system procedure library, 
SYS1.PR0CLIB. This contains the job 
control procedures that have been 
cataloged for your installation. 



How to Use a Library 



The ways in which the libraries described 
above can be used are described in the 
following sections. 



BY THE LINKAGE EDITOR OR LOADER 



The output from the linkage editor is 
usually placed on a private program 
1 ibrary . 

The automatic call library used as input 
to the linkage editor or loader (see 
Chapter 5) can be SYSl.LINKLIB, a private 
program library, or a subroutine library. 

In each case, the processing of 
directory entries is performed by the 
operating system. 

When you are adding a member to a 
library, you must specify the member name 
as follows: 

• When a single module is produced as 
output from the linkage editor, the 
member name can be specified as part of 
the data set name (see later in this 
chapter) . 

• When more than one module is produced as 
output from the linkage editor, the 
member name for the first module can be 
specified as part of the data set name 
or in the NAME option or NAME control 
statement. The member names for the 
subsequent modules must be specified in 
the NAME option or the NAME control 
statement. 



BY THE OPERATING SYSTEM 



When you request the execution of a load 
module in an EXEC statement or CALL 
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command, the operating system must be able 
to retrieve the load module from a library. 
For a CALL command, this library is 
specified explicitly or implicitly in the 
command. For an EXEC statement, the 
following rules apply. 

The operating system will assume the 
load module is a member of SYSl.LINKLIB, 
and will search in the directory for that 
library for the name you have specified, * 
unless you have also specified that the 
load module is in a private library, in one 
of the following ways. 

If the load module has been added to the 
private library in a previous step of the 
job (usually a link- edit step) and the 
member name was specified as part of the 
data set name, then you can refer, in the 
EXEC statement, to the DD statement 
defining the library instead of specifying 
the load module name. The library must 
have been given the disposition PASS. 

If the load module exists on the private 
library before the job starts, then you 
have several ways of defining the library. 

You can define the library in a DD 
statement, with the ddname JOBLIB, 
immediately after the JOB statement. This 
library will be used in place of 
SYSl.LINKLIB for all the steps of the job. 
If any load module is not found on the 
private library, the system will then look 
for it on SYSl.LINKLIB. 

You can define the library in a DD 
statement with the ddname STEPLIB, at any 
point in the job control procedure. The 
private library will be used in place of 
SYSl.LINKLIB, or any library specified in a 
JOBLIB DD statement, for the job step in 
which it appears (though it can also be 
"passed" to subsequent job steps in the 
normal way) . If any load module is not 
found on the private library, the system 
will look for it on the library specified 
in the JOBLIB DD statement (if used) or on 
SYSl.LINKLIB. The STEPLIB DD statement can 
be used in a cataloged procedure. 

Alternatively, if you specify 
SYSl.LINKLIB in the JOBLIB or STEPLIB DD 
statements, and then concatenate the 
private library to it, the private library 
will be used only if a load module cannot 
be first found on SYSl.LINKLIB. 



If you are adding a new member to a 
library, its directory entry will be made 
by the operating system when the associated 
file is closed, using the merrber naire 
specified as part of the data set name. 

If you are accessing a member of a 
library, its directory entry can be found 
by the operating system from the member 
name that you specify as part of the data 
set name. 

More than one member of the same library 
can be processed by the same PL/I program, 
but only one such output file can be open 
at any one time. Different irerobers are 
accessed by giving the member name in a DD 
statement. 



Creating a Library 



To create a library include in your job 
step a DD statement containing the 
information given in Figure 10-1. The 
information required is similar to that for 
a consecutively-organized data set (see 
Chapter 8) except for the SPACE parameter. 



Information 
Required 

Type of device that will 
process the library 

Serial, number of the volume 
that will contain the library 

Name of the library 

Amount of space required 
for the library 

Disposition of the library 



Parameter of 
DD statement 

UNIT= 

VOLUME=SER 

DSNAME= 
SPACE= 

DISP= 



Figure 10-1. Information required 

when creating a library 



SPACE PARAMETER 



The SPACE parameter in a DD statement that 
defines a library must always be of the 
form: 



BY YOUR PROGRAM 



Libraries can be used directly by a PL/I 
program. 



SPACE= (units, (quantity, 

increment, directory)) 

Although you can omit the third term 
(increment) , indicating its absence by a 
comma, the last term, specifying the number 
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of directory blocks to be allocated, must 
always be present. 

The amount of auxiliary storage required 
for a library depends on the number and 
sizes of the members to be stored in it and 
on how often members will be added or 
replaced. (space occupied by deleted 
members is not released.) The number of 
directory blocks required depends on the 
number of members and the number of 
aliases. Although you can specify an 
incremental quantity in the SPACE parameter 
that will allow the operating system to 
obtain more space for the data set if 
necessary, both at the time of creation and 
when new members are added, the number of 
directory blocks is fixed at the time of 
creation and cannot be increased. 

If the data set is likely to be large or 
you expect to do a lot of updating, it 
might be best to allocate a full volume. 
Otherwise, make your estimate as accurate 
as possible to avoid wasting space or time 
recreating the data set. 

The number of directory entries that a 
25 6- byte directory block can contain 
depends on the amount of user data included 
in the entries. The maximum length of an 
entry is 74 bytes, but the entries produced 
by the linkage editor vary in length 
between 34 bytes and 52 bytes, which is 
equivalent to between four and seven 
entries per block. 

For example, the DD statement: 

//PDS DD UNIT=2311,VOLUME=SER=3412, 

// DSNAME=ALIB, 

// SPACE=(CYL, (50,, 10)) , 

// DISP=(,CATLG) 

requests the job scheduler to allocate 50 
cylinders of the 2311 disk pack with serial 
number 3412 for a new partitioned data set 
named ALIB, and to enter this name in the 
system catalog. The last term of the SPACE 
parameter requests that part of the space 
allocated to the data set be reserved for 
ten directory blocks. 



Creating a Library Member 



The members of a library must have 
identical characteristics otherwise you may 
subsequently have difficulty retrieving 
them. This is necessary because the volume 
table of contents (VTOC) will contain only 
one data set control block (DSCB) for the 
library and not one for each member. When 
using a PL/I program to create a member, 
the operating system creates the directory 
entry; you cannot place information in the 



user data field. 

When creating a library and a member at 
the same time, the DD statement must 
include all the parameters listed under the 
heading "Creating a Library," earlier in 
this chapter (although you can omit the 
DISP parameter if the data set is to be 
temporary) . The DSNAME parameter must 
include the member name in parentheses. 
For example, DSNAME=ALIB (MEM1) names the 
member MEM1 in the data set ALIB. If the 
member is placed in the library by the 
linkage editor, you can use the linkage 
editor NAME statement or the NAME compiler 
option instead of including the member name 
in the DSNAME parameter. You must also 
describe the characteristics of the member 
(record format, etc.) either in the DCB 
parameter or in your PL/I program; these 
characteristics will also apply to other 
members added to the data set. 

When creating a member to be added to an 
existing library, you will not need the 
SPACE parameter; the original space 
allocation applies to the whole of the 
library and not to an individual member. 
Furthermore, you will not need to describe 
the characteristics of the member, since 
these are already recorded in the DSCB for 
the library. 

To add two or more members to a library 
in one job step, you must include a ED 
statement for each member, and you must 
close one file that refers to the library 
before you open another. 



Examples 



The use of the cataloged procedure PLIXC to 
compile a simple PL/I program and place the 
object module in a new library named EXLIB 
is shown in Figure 10-2.. The DD statement 
that defines the new library and names the 
object module overrides the DD statement 
SYSLIN in the cataloged procedure. (The 
PL/ I program is a function procedure that, 
given two values in the form of the 
character string produced by the TIME 
built-in function, returns the difference 
in milliseconds.) 

The use of the cataloged procedure 
PLIXCL to compile and link edit a PL/I 
program and place the load module in the 
| existing library "PUBPGM" is shown in 
Figure 10-3. (The PL/I program lists the 
names of the members of a library. ) 

To use a PL/I program to add or delete 
one or more records within a member of a 
library, you must rewrite the entire member 
in another part of the library; this is 
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//OFT10#2 JOB 

//STEP1 EXEC PLIXC 

//PLI . SYSLIN DD DSN AME=EXLIB (ELAPSE) , UNIT=2 311 , VOL=SER=Dl 8 6 , 

// SPACE=(CYL, (10 , ,2)) ,DISP= (NEW,KEEP) 

//PLI. SYS IN DD * 

ELAPSE: PROC (TIMEl ,TIME2) ; 

DCL (TIMEl, TIME2) CHAR(9), 
Hi PIC '99' DEF TIMEl, 
Ml PIC '99' DEF TIMEl POS(3) f 
MSI PIC '99999' DEF TIMEl POS(5), 
H2 PIC '99' DEF TIME2, 
M2 PIC '99' DEF TIME2 POS(3), 
MS2 PIC '99999' DEF TIME2 POS(5), 
ETIME FIXED DEC (7); 

IF H2<H1 THEN H2=H2+24; 

ETIME=((H2*60+M2)*600000+MS2)-((H1*60+M1)*600000+MS1); 
RETURN (ETIME); 
END ELAPSE; 
/* 

Figure 10-2. Creating new libraries for compiled object modules 



//OPT10#3 JOB 

//STEP1 EXEC PLIXCL 
//PLI.SYSIN DD * 

MNAME : PROC OPTI ONS ( MAI N ) ; 

DCL LINK FILE RECORD SEQUENTIAL INPUT, 
1 DIRBLK, 
2 COUNT BIT (16), 
2 ENTRIES (254) CHAR(l), 

1 ENTRY BASED (A) , 
2 NAME CHAR (8) , 
2 TTR CHAR (3) , 
2 INDIC, 
3 ALIAS BIT(l), 
3 TTRS BIT (2) , 
3 USERCT BIT (5), 

(LEN,PTR) FIXED BIN(31); 

ON ENDFILE(LINK) GO TO FINISH; 

OPEN FILE (LINK) ; 

NEXTBLK: READ FILE (LINK) INTO (DIRBLK) ; 
LEN= COUNT; 
PTR=1; 

NEXTENT: A=ADDR( ENTRIES ( PTR) ) ; 
PUT FILE(SYSPRINT) SKIP LIST (NAME) ; 
PTR=PTR+ 12+2 +USERCT ; 
IF PTR+2>LEN THEN GO TO NEXTBLK; 
GO TO NEXTENT; 

FINISH: CLOSE FILE (LINK) ; 
END MNAME; 
/* 
//LKED. SYSLMOD DD DSN=PUBPGM(DIRLIST) ,DISP=0LD,V0L=SER=D186 , UNIT=2311 

Figure 10-3. Placing a load module in an existing library 
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//OPTlO#4 JOB 

//STEP1 EXEC PLIXCLG 
//PLI.SYSIN DD * 

NMEM : PROC OPTI ONS ( MAI N ) ; 

DCL OUT FILE RECORD SEQUENTIAL OUTPUT, 
I OFI ELD CHAR (80) BASED ( A) ; 

ON ENDFILE(IN) GO TO FINISH; 

NEXT: READ FILE (IN) SET (A); 

WRITE FILE (OUT) FROM (IOFIELD) ; 
GO TO NEXT; 
FINISH: END NMEM; 
/* 

//GO.OUT DD DSN=ALIB(NMEM) ,UNIT=2311 ,V0L=SER=D186, 
// DISP=(NEW,CATLG),SPACE=(CYL, (10,1,1)), 

// DCB= (RECFM=FB , BLKSI ZE=4 00 , LRECL*80) 

//GO. IN DD * 

(insert here data to be included in the input stream) 
/* 

Figure 10-4. Creating a library member in a PL/I program 



//OPT10#5 JOB 

//STEPl EXEC PLIXCLG 
//PLI.SYSIN DD * 

UPDTM: PROC OPTIONS (MAIN) ; 

DCL (OLD, NEW) FILE RECORD SEQUENTIAL, 
DATA CHAR (80); 

ON ENDFILE(OLD) GO TO FINISH; 

OPEN FILE (OLD) INPUT , FILE (NEW) OUTPUT TITLE ( , OLD» ) ; 
NEXT: READ FILE(OLD) INTO (DATA); 

IF DATA=« ' THEN GO TO NEXT; 

WRITE FILE(NEW) FROM ( DATA) ; 

PUT FILE (SYSPRINT) SKIP LIST (DATA); 

GO TO NEXT; 
FINISH: CLOSE FILE (OLD) , FILE (NEW) ; 

END UPDTM; 
/* 
//GO. OLD DD DSNAME=ALIB(NMEM),DISP=OLD 



Figure 10-5. Updating a library member 



rarely an economic proposition, since the 
space originally occupied by the member 
cannot be used again. You must use two 
files in your PL/I program, but both can be 
associated with the same DD statement. The 
program shown in Figure 10-5 updates the 
member created by the program in Figure 10- 
4; it copies all the records of the 
original member except those that contain 
only blanks. 



Library Structure 

The structure of a library is illustrated 
in Figure 10-6. The directory of a library 
is a series of records (entries) at the 
beginning of the data set; there is at 
least one directory entry fcr each irember. 
Each entry contains a member name, the 
relative address of the irember within the 
library, and a variable amount of user 
data. The entries are arranged in 
ascending alphameric order of member names. 

A directory entry can contain up to 62 
bytes of user data (information inserted by 
the program that created the member). An 
entry that refers to a member (load module) 
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bit 



Note: 

pointers contain relative 
addresses of locations 
within member. 



name 

1 alias 


number of ptrs in 
user data field 


number of halfwords in user 
data field (inc pointers) 



k 



byte 1 1 of 
directory entry 



J 



byte 



10 11 



12 



61 



member name 


track no. relative 
to start of d.s. 


rel block 
no. on 
track 




optional variable user data (max 62 bytes) 



contents of a directory entry 



"1 f 

256 byte directory block 1 - 



— 


Directory entry 
for member A 


Directory entry 
for member B 


Directory entry 
for member C 




Directory entry 
for member K 




member C 


space from 
deleted members 




member B 


member K 




member K (cont'd) 




member K (cont'd 


) 


member A 


member A (cont'd) 


available area 























Figure 10-6. structure of a library 
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written by the linkage editor includes user 
data in a standard format, described in the 
manual system Control Blocks . 

If you use a PL/ I program to create a 
member, the operating system creates the 
directory entry for you and you cannot 
write any user data. However, you can use 
assembler language macro instructions to 
create a member and write your own user 
data; the method is described in the manual 
supervisor and Data Management Services . 

Directory entries are stored in fixed- 
length blocks of 256 bytes, each containing 



a 2-byte count field specifying the number 
of active bytes in a block, and as many 
complete entries as will fit into the 
remaining 254 bytes. The directory is in 
effect a sequential data set that contains 
fixed-length unblocked records, and can be 
read as such. 

The program illustrated in Figure 10-3 
demonstrates a method of extracting 
information from directory entries. The 
program lists the names of all the members 
of a library; the library must be defined, 
when the program is executed, in a ED 
statement with the name LINK. 
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Chapter 11: Cataloged Procedures 



This chapter describes the standard 
cataloged procedures supplied by IBM for 
use with the OS PL/I Optimizing Compiler, 
explains how to invoke them, and how to 
make temporary or permanent modifications 
to them. 

A cataloged procedure is a set of job 
control statements stored in a system 
library, the procedure library 
(SYSl.PROCLIB) . It comprises one or more 
EXEC statements, each of which may be 
followed by one or more DD statements. You 
can retrieve the statements by naming the 
cataloged procedure in the PROC parameter 
of an EXEC statement in the input stream. 
When the operating system processes this 
EXEC statement, it replaces it in the input 
stream with the statements of the cataloged 
procedure. 

The use of cataloged procedures saves 
time and reduces errors in coding 
frequently used sets of job control 
statements. If the statements in a 
cataloged procedure do not match your 
requirements exactly, you can easily modify 
them or add new statements for the duration 
of a job. It is recommended that each 
installation review these procedures and 
modify them to obtain the most efficient 
use of the facilities available and to 
allow for installation conventions; refer 
to "Permanent Modification," later in this 
chapter. 



Invoking a Cataloged Procedure 



statement, it extracts the statements of 
the cataloged procedure froir the procedure 
library and substitutes them for the EXEC 
statement in the input job stream. If you 
include the parameter MSGLEVEL=1 in your 
JOB statement, the operating system will 
include the original EXEC statement in its 
listing, and will add the statements of the 
cataloged procedure. In the listing, 
cataloged procedure statements are 
identified by XX or x/ as the first two 
characters; X/ signifies a statement that 
has been modified for the current 
invocation of the cataloged procedure. 

An EXEC statement identifies a job step , 
which can require either the execution of a 
program or the invocation of a cataloged 
procedure. A cataloged procedure includes 
one or more EXEC statements , which identify 
procedure steps . However, an EXEC 
statement in a cataloged procedure cannot 
invoke another cataloged procedure; it must 
request the execution of a program. 

It may be necessary for you to modify 
the statements of a cataloged procedure for 
the duration of the job step in which it is 
invoked, either by adding DD statements or 
by overriding one or more parameters in the 
EXEC or DD statements. For example, 
cataloged procedures that invoke the 
compiler require the addition of a DD 
statement with the name SYS IN to define the 
data set containing the source statements. 
Also, whenever you use more than one 
standard link-edit procedure step in a job, 
you must modify all but the first cataloged 
procedure that you invoke if you want to 
execute more than one of the load modules. 



To invoke a cataloged procedure, specify 
its name in the PROC parameter of an EXEC 
statement. For example, to use the 
cataloged procedure PLIXC, you could 
include the following statement in the 
appropriate position among your other job 
control statements in the input stream: 

//stepname EXEC PROC=PLIXC 

You need not code the keyword PROC; if the 
first operand in the EXEC statement does 
not begin PGM= or PROC=, the job scheduler 
interprets it as the name of a cataloged 
procedure. The following statement is 
equivalent to that given above: 

//stepname EXEC PLIXC 

When the operating system meets the name 
of a cataloged procedure in an EXEC 



Multiple invocation of Cataloged 
Procedures 



You can invoke different cataloged 
procedures, or invoke the same cataloged 
procedure several times, in the same job. 
No special problems are likely to arise 
unless more than one of these cataloged 
procedures involves a link- edit procedure 
step, in which case you must take the 
following precautions to ensure that all 
your load modules can be executed. 

The linkage editor always places a load 
module that it creates in the standard data 
set defined by the DD statement with the 
name SYSLMOD. In the absence of a linkage 
editor NAME statement (or the NAME compiler 
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option), it uses the member name specified 
in the DSNAME parameter as the name of the 
module. In the standard cataloged 
procedures, the DD statement with the name 
SYSLMOD always specifies a temporary 
library named SSGOSET, and gives the load 
module the member name GO. 

Consider what will happen if, for 
example, you use the cataloged procedure 
PLIXCLG twice in a job to compile, link 
edit, and execute two PL/I programs, and do 
not name each of the two load modules that 
will be created by the linkage editor. The 
linkage editor will name the first load 
module GO, as specified in the first DD 
statement with the name SYSLMOD. It will 
not be able to use the same name for the 
second load module since the first load 
module still exists in the library SSGOSET; 
it will allocate a temporary name to the 
second load module (a name that is not 
available to your program). Step GO of the 
cataloged procedure requests the operating 
system to initiate execution of the load 
module named in the first DD statement with 
the name SYSLMOD in the step LKED, that is, 
to execute the module named GO from the 
library SSGOSET. Consequently, the first 
load module will be executed twice and the 
second not at all. 



To prevent this, 
following methods: 



use one of the 



Delete the library SSGOSET at the end of 
the step GO of the first invocation of 
the cataloged procedure by adding a DD 
statement of the form: 

//GO. SYSLMOD DD DSN= SSGOSET, 
DI SP= ( OLD , DELETE ) 

Modify the DD statement with the name 
SYSLMOD in the second and subsequent 
invocations of the cataloged procedure 
so as to vary the names of the load 
modules. For example: 

//LKED. SYSLMOD DD DSN=6SGQSET (GOl) 

and so on. 

Use the NAME compiler option to give a 
different name to each load module and 
change your job control statements to 
specify the execution of the load 
modules with these names. 



Dedicated Data Sets 



Many of the processing programs in the 
operating system, including the optimizing 
compiler and the linkage editor, use 
temporary workfiles. To avoid allocating 



data sets for these workfiles each time 
they are required, an installation using 
the MVT operating systeir can dedicate one 
or more data sets for temporary workfiles, 
and these remain permanently allocated. 

The standard cataloged procedures allow 
you to assign dedicated data sets to the 
optimizing compiler and linkage editor. 
The DD statements for workfiles have the 
ddname SYSUTl. In these DD statements, the 
DSNAME parameter is coded: 

DSNAME=S 6 ddname 

where "ddname" is the ddname of that DD 
statement. Your installation must have 
assigned these names to the dedicated data 
sets, otherwise you must override the DD 
statement in the cataloged procedure in 
order to specify the names used by ycur 
installation. 

If the system cannot assign the 
dedicated data set to your job step, it 
creates a temporary data set instead. For 
full details of dedicated data sets see the 
OS System Programmer's Guide . 



Multitasking Using cataloged Procedures 



When you use a cataloged procedure to link 
edit a multitasking program, you must 
ensure that the load module includes the 
multitasking versions of the PL/I resident 
library subroutines. To enable you to 
select the appropriate library, the 
cataloged procedures that invoke the 
linkage editor and the loader include a 
symbolic parameter (6LKLBDSN) in the DSNAME 
parameter of the DD statement SYSLIB, which 
defines the data set to be used as the 
automatic call library. This data set is 
described in chapter 5. The default value 
of this symbolic parameter is SYS1.PLIBASE, 
which is the name of the non-multitasking 
("base") library. 

To ensure that the multitasking library 
(SYSl.PLITASK) is searched before the base 
library, include the parameter 
LKLBDSN= •SYSl.PLITASK* in the EXEC 
statement that invokes the cataloged 
procedure; for example: 

//STEPA EXEC PLIXCLG ,LKLBDSN=« SYSl.PLITASK' 

The DD statement SYSLIB is always 
followed in the standard cataloged 
procedures by another, unnamed, DD 
statement that includes the parameter 
DSNAME=SYS1.PLIBASE. The effect of this 
statement is to concatenate the base 
library with the multitasking library, if 
the latter is used; the base library can 
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then be searched for any subroutine common 
to multitasking and non -multi tasking and 
therefore not included in the multitasking 
library. When the non-multitasking library 
is selected, the second DD statement has no 
effect. 

The use of the symbolic parameter 
6LKLBDSN means that for non-multitasking 
programs, SYSl.PLIBASE is concatenated with 
itself. This has no effect other than a 
very small increase in job scheduling time, 
but does avoid the need for different 
cataloged procedures for link editing 
multitasking and non-multitasking programs. 



Modifying Cataloged Procedures 



You can modify a cataloged procedure 
temporarily by including parameters in the 
EXEC statement that invokes the cataloged 
procedure or by placing additional DD 
statements after the EXEC statement. 
Temporary modifications apply only for the 
duration of the procedure step in which the 
procedure is invoked and only to that 
procedure step; they do not affect the 
master copy of the cataloged procedure 
stored in the procedure library. 

Alternatively, you can modify a 
cataloged procedure permanently by 
rewriting the job control statements that 
are stored in the procedure library. 
Permanent modification should be made only 
by system programmers responsible for 
maintaining the procedure library. Some of 
the considerations that may influence their 
decisions to modify the standard cataloged 
procedures are discussed below. 



TEMPORARY MODIFICATION 



Temporary modifications can apply to EXEC 
or DD statements in a cataloged procedure. 
To change a parameter of an EXEC statement, 
you must include a corresponding parameter 
in the EXEC statement that invokes the 
cataloged procedure; to change one or more 
parameters of a DD statement, you must 
include a corresponding DD statement after 
the EXEC statement that invokes the 
cataloged procedure. Although you may not 
add a new EXEC statement to a cataloged 
procedure, you can always include 
additional DD statements. 



EXEC Statement 



If a parameter of an EXEC statement that 
invokes a cataloged procedure has an 
unqualified name, the parameter applies to 
all the EXEC statements in the cataloged 
procedure. The effect on the cataloged 
procedure depends on the parameters , as 
follows : 

• PARM applies to the first procedure step 
and nullifies any other PARM parameters. 

• COND and ACCT apply tc all the procedure 
steps. 

• TIME and REGION apply to all the 
procedure steps and override existing 
values. 

For example, the statement: 

//stepname EXEC PLIXCLG, PARM= f SIZE (MAX) * , 
REGION=144K 

invokes the cataloged procedure PLIXCLG, 
substitutes the option SIZE (MAX) for OBJECT 
and NODECK in the EXEC statement for 
procedure step PLI, and nullifies the PARM 
parameter in the EXEC statement for 
procedure step LKED; it also specifies a 
region size of 144K for all three procedure 
steps . 

To change the value of a parameter in 
only one EXEC statement of a cataloged 
procedure, or to add a new parameter to one 
EXEC statement, you must identify the EXEC 
statement by qualifying the name of the 
parameter with the name of the procedure 
step. For example, to alter the region 
size for procedure step PLI cnly in the 
preceding example, code: 

//stepname EXEC PROC=PLlXCLG, 

PARM=' SIZE (MAX) • ,REGION.PLI=144K 

A new parameter specified in the 
invoking EXEC statement overrides 
completely the corresponding parameter in 
the procedure EXEC statement. 

You can nullify all the options 
specified by a parameter by coding the 
keyword and equal sign without a value. 
For example, to suppress the bulk of the 
linkage editor listing when invoking the 
cataloged procedure PLIXCLG, code: 

//stepname EXEC PLIXCLG,PARM.LKED= 



DD Statement 



To add a DD statement to a cataloged 
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procedure, or to modify one or more 
parameters of an existing DD statement, you 
must include, in the appropriate position 
in the input stream, a DD statement with a 
name of the form "procstepname.ddname" . If 
"ddname" is the name of a DD statement 
already present in the procedure step 
identified by "procstepname," the 
parameters in the new DD statement override 
the corresponding parameters in the 
existing DD statement; otherwise, the new 
DD statement is added to the procedure 
step. For example, the statement: 

//PLI.SYSIN DD * 

adds a DD statement to the procedure step 
PLI of cataloged procedure PLIXC and the 
effect of the statement: 

//PLI.SYSPRINT DD SYSOUT=C 

is to modify the existing DD statement 
SYSPRINT (causing the compiler listing to 
be transmitted to the system output device 
of class C) . 

Overriding DD statements must follow the 
EXEC statement that invokes the cataloged 
procedure in the same order as the 
corresponding DD statements of the 
cataloged procedure. DD statements that 
are being added must follow the overriding 
DD statements for the procedure step in 
which they are to appear. 

To override a parameter of a DD 
statement, code either a revised form of 
the parameter or a replacement parameter 
that performs a similar function (for 
example, SPLIT for SPACE) . To nullify a 
parameter, code the keyword and equal sign 
without a value. You can override DCB 
subparameters by coding only those you wish 
to modify; that is, the DCB parameter in an 
overriding DD statement does not 
necessarily override the entire DCB 
parameter of the corresponding statement in 
the cataloged procedures. 



In general, installation conventions 
will dictate the options that you include 
in the PARM, UNIT, and SPACE parameters of 
the cataloged procedures, and also the 
blocking factors for output data sets. 

If your installation uses the MVT 
control program of the operating system, 
you may need to modify some cr all cf the 
REGION parameters. 

The minimum region size for compilation 
should be at least 8K bytes larger than the 
largest value that will be specified in the 
SIZE compiler option, ^excluding SIZE (MAX). 

In cataloged procedures that invcke the 
linkage editor, a region size of 100K is 
specified for the link-edit procedure step. 

You can reduce this regicn size if you 
are using the 44K F- level linkage editor. 
In general, the region size should fce at 
least 8K bytes larger than the design size 
for the particular version cf the linkage 
editor being used. You must alter the 
region size if you are using the 128K F- 
level linkage editor. 

Under MVT, the operating system requires 
up to 52K bytes of main storage within a 
region when initiating or terminating a job 
step. If you specify a region size of less 
than 52K bytes, completion cf a job iray be 
held up until 52K bytes are available. 

The minimum region size used by MVT is 
dependent on the installation, and is 
defined at system generation. There is 
nothing to be gained in reducing the region 
size below this value. 

If your installation uses MFT only, you 
can delete the REGION parameter froir all 
cataloged procedures, otherwise it will be 
ignored . 



IBM-Supplied Cataloged Procedures 



PERMANENT MODIFICATION 



To make permanent modifications to a 
cataloged procedure, or to add a new 
cataloged procedure, use the system utility 
program IEBUPDTE, which is described in the 
utilities publication. The following 
paragraphs discuss some of the factors you 
should have in mind when considering 
whether to modify the standard cataloged 
procedures for your installation. For 
further information on writing installation 
cataloged procedures see the system 
programmer ' s guide . 



The standard PI/I cataloged procedures 
supplied for use with the optimizing 
compiler are: 



PLIXC Compile only 

PLIXCL Compile and link edit 

PLIXCIG Compile, link edit, and execute 

PLIX1G Link edit and execute 

PLIXCG Compile, load- and- execute 

PLIXG Load- and- execute 
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The individual statements of the 
cataloged procedures are not fully 
described, since all the parameters are 
discussed elsewhere in this publication. 
These cataloged procedures do not include a 
DD statement for the input data set; you 
must always provide one. The example shown 
in Figure 11-1 illustrates the JCL 
statements you might use to invoke the 
cataloged procedure PLIXCLG to compile, 
link edit, and execute, a PL/I program. 



//COLEGO JOB 

//STEP1 EXEC PLIXCLG 

//PLI.SYSIN DD * 



ddname PLI.SYSIN. 

The OBJECT option causes the compiler tc 
place the object module, in a form suitable 
for input to the linkage editor, in the 
standard data set defined by the ED 
statement with the name SYSLIN. This 
statement defines a temporary data set 
named SSLOADSET on a magnetic-tape cr 
direct- access device? if you want to retain 
the object module after the end of ycur 
job, you must substitute a permanent name 
for SSLOADSET (that is, a name that does 
not commence SS) and specify KEEP in the 
appropriate DISP parameter for the last 
procedure step in which the data set is 
used. 



(insert here PL/I program to be 
compiled) 



/* 

Figure 11-1. 



Invoking a cataloged 
procedure 



No IBM-supplied cataloged procedure is 
provided to produce an object module on 
punched cards. You can temporarily modify 
any of the cataloged procedures that have a 
compile step to produce a punched card 
output; an example is shown in Figure 11-2. 



//stepname EXEC PLIXCLG, 

// PARM. PLI= ■• OBJECT , DECK • 

//PLI. SYS PUNCH DD SYSOUT=B 

//PLI.SYSIN DD ... 



Figure 11-2. 



Modifying a cataloged 
procedure to produce a 
punched card output 



Compile Only (PLIXC) 



This cataloged procedure, shown in Figure 
11-3, comprises only one procedure step, in 
which the options specified for the 
compilation are OBJECT and NODECK. (IELOAA 
is the symbolic name of the compiler.) In 
common with the other cataloged procedures 
that include a compilation procedure step, 
PLIXC does not include a DD statement for 
the input data set; you must always supply 
an appropriate statement with the qualified 



The term MOD in the DISP parameter 
allows the compiler to place more than one 
object module in the data set, and PASS 
ensures that the data set will be available 
to a later procedure step providing a 
corresponding DD statement is included 
there. 

The SPACE parameter allows an initial 
allocation of 250 eighty-byte records and, 
if necessary, 15 further allocations of 100 
records (a total of 1750 records, which 
should suffice for most applications). 



Compile and Link-edit (PLIXCL) 



This cataloged procedure, shown in Figure 
11-4, comprises two procedure steps: PLI, 
which is identical with cataloged procedure 
PLIXC, and LKED, which invokes the linkage 
editor (symbolic name IEWL) to link edit 
the object module produced in the first 
procedure step. 

Input data for the compilation procedure 
step requires the qualified ddname 
PLI.SYSIN. The COND parameter in the EXEC 
statement LKED specifies that this 
procedure step should be bypassed if the 
return code produced by the compiler is 
greater than 9 (that is, if a severe or 
unrecoverable error occurs during 
compilation) . 

The DD statement with the name SYSLIB 
specifies the PL/I resident library, from 
which the linkage editor will obtain 
appropriate modules for inclusion in the 
load module. The linkage editor always 
places the load modules it creates in the 
standard data set defined by the CD 
statement with the name SYSLMOD. This 
statement in the cataloged procedure 
specifies a new temporary library 6SGOSET, 
in which the load module will be placed and 
given the member name GO (unless you 
specify the NAME compiler option for the 
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//PLIXC PROC 

//PLI EXEC PGM=IELOAA,PARM=' OBJECT, NODECK f ,REGION=100K 

//SYSPRINT DD SYSOUT=A, DCB=(RECFM=VBA,LRECL=125,BIKSIZE=629) 

//SYSLIN DD DSN=ggLOADSET,DlSP= (MOD, PASS), UNIT=SYSSQ, 

// SPACE=(80 f (250, 100)) 

//SYSUTl DD DSN=ggSYSUTl,UNlT=SYSDA,SPACE=(1024, (60,60),, CONTIG) , 

// DCB=BLKSIZE=1024 

Figure 11-3. Cataloged procedure PLIXC 



//PLIXCL PROC LKLBDSN= , SYSl.PLIBASE t 

//PLI EXEC PGM=IEL0AA, PARM=" OBJECT, NODECK f ,REGION=100K 

//SYSPRINT DD SYSOUT=A, DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSLIN DD DSN=gg LOADS ET,DISP= (MOD, PASS) ,UNIT=SYSSQ, 

// SPACE=(80, (250, 100)) 

//SYSUTl DD DSN=ggSYSUTl,UNTT=SYSDA,SPACE= (1024, (60, 60),, CONTIG), 

// DCB=BLKSIZE=1024 

//LKED EXEC PGM=IEWL,PARM=* XREF,LIST' ,COND= (9 ,LT, PLI) , REGION=100K 

//SYSLIB DD DSN=6LKLBDSN,DISP=SHR 

// DD DSN=SYSl.PLIBASE,DISP=SHR 

//SYSLMOD DD DSN=ggGOSET (GO) , DISP= (MOD, PASS) ,UNIT=SYSDA, 

// SPACE=( 1024, (50,20,1) ,RLSE) 

//SYSUTl DD DSN=ggSYSUTl,UNlT=SYSDA,SPACE= (1024, (200,20)), 

// DCB=BLKSIZE=1024 

//SYSPRINT DD SYSOUT=A 

//SYSLIN DD DSN=ggLOADSET,DlSP= (OLD, DELETE) 

// DD DDNAME=SYSIN 



Figure 11-4. Cataloged procedure PLIXCL 



//PLIXCLG PROC LKLBDSN='SYSl. PLI BASE' 

//PLI EXEC PGM=IEL0AA, PARM= , OBJECT,NODECK , ,REGION=100K 

//SYSPRINT DD SYSOUT=A,DCB= (RECFM=VBA,LRECL=125 , BLKSIZE=629) 

//SYSLIN DD DSN=ggLOADSET,DlSP=(MOD,PASS),UNIT=SYSSQ, 

// SPACE= (80, (250,100)) 

//SYSUTl DD DSN=ggSYSUTl,UNlT==SYSDA,SPACE=(1024, (300,60) , , CONTIG) , 

// DCB=BLKSIZE=1024 

//LKED EXEC PGM=IEWL, PARM= *XREF, LIST • , COND=(9,LT,PLI) ,REGION=100K 

//SYSLIB DD DSN=gLKLBDSN,DISP=SHR 

// DD DSN=SYSl.PLIBASE,DISP=SHR 

//SYSLMOD DD DSN= g gGOSET (GO) ,DISP= (MOD , PASS) , UNIT=SYSDA , 

// SPACE= (1024, (50, 20,1), RLSE) 

//SYSUTl DD DSN=ggSYSUTl,UNlT=SYSDA,SPACE=(1024, (200,20)) , 

// DCB=BLKSIZE=1024 

//SYSPRINT DD SYSOUT=A 

//SYSLIN DD DSN=ggLOADSET,DlSP= (OLD, DELETE) 

// DD DDNAME=SYSIN 

//GO EXEC PGM=*. LKED. SYSLMOD, COND=( (9 ,LT, PLI), (9, LT, LKED)), 

// REGION=100K 

//SYSPRINT DD SYSOUT=A 



Figure 11-5. Cataloged procedure PLIXCLG 
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//PLIXLG PROC LKLBDSN^SYSl. PLI BASE' 

//LKED EXEC PGM=IEWL,PARM=' XREF,LIST' ,REGION=100K 

//SYSLIB DD DSN=gLKLBDSN,DISP=SHR 

// DD DSN=SYS1.PLIBASE,DISP=SHR 

//SYSLMOD DD DSN=£6GOSET (GO) ,DISP= (MOD, PASS) ,UNIT=SYSSQ, 

// SPACE=( 1024, (50,20,1) ,RLSE) 

//SYSUT1 DD DSN=SSSYSUTl,UNIT=SYSDA,SPACE=(1024, (200,20)), 

// DCB=BLKSIZE=1024 

//SYSPRINT DD SYSOUT=A 

//SYSLIN DD DNAME=SYSIN 

//GO EXEC PGM=*. LKED. SYSLMOD, COND= (9, LT, LKED) ,REGION=100K 

//SYSPRINT DD SYSOUT=A 

Figure 11-6. Cataloged procedure PLIXLG 



compiler procedure step) . In specifying a 
temporary library, the cataloged procedure 
assumes that you will execute the load 
module in the same job; if you want to 
retain the module , you must substitute your 
own statement for the DD statement with the 
name SYSLMOD. 

The last statement, DDNAME=SYSIN, 
illustrates how to concatenate a data set 
defined by a DD statement with the name 
SYSIN with the primary input (SYSLIN) to 
the linkage editor. You could place 
linkage editor control statements in the 
input stream by this means, as described in 
Chapter 5. 



Compile, Link-edit, and Execute 
(PLIXCLG) 

This cataloged procedure, shown in Figure 
11-5, comprises three procedure steps, PLI 
and LKED, which are identical with the two 
procedure steps of PLIXCL, and GO, in which 
the load module created in the step LKED is 
executed. The third procedure step will be 
executed only if no severe or unrecoverable 
errors occur in the preceding procedure 
steps. 

Input data for the compilation procedure 
step should be specified in a DD statement 
with the name PLI. SYSIN, and for the 
execution procedure step in a DD statement 
with the name GO. SYSIN. 



Link-edit and Execute (PLIXLG) 



statement with the name SYSLIN does not 
define a data set, but merely refers the 
operating system to the ED statement SYSIN, 
which you must supply with the qualified 
ddname IKED.SYSIN. This DD statement 
defines the data set froir which the linkage 
editor will obtain its primary input. 
Execution of the procedure step GO is 
conditional on successful execution cf the 
procedure step LKED only. 



Compile, Load, and Execute (PLIXCG) 



This cataloged procedure, shown in Figure 
11-7, achieves the same results as PLIXCLG 
but uses the loader instead of the linkage 
editor. However, instead of using three 
procedure steps (compile, link edit, and 
execute), it has only two (compile, and 
load-and-execute) . In the second procedure 
step, the loader program is executed; this 
program processes the object module 
produced by the compiler and executes the 
resultant executable program immediately. 
Input data for the compilation procedure 
step requires the qualified ddname 
PLI. SYS IN. 

The REGION parameter of the EXEC 
statement GO specifies 100K tytes. Since 
the loader requires about 17K bytes of main 
storage, there are about 83K bytes for your 
program; if this is likely to be 
insufficient, you must modify the REGION 
parameter. The use of the loader imposes 
certain restrictions on your PL/ I program; 
before using this cataloged procedure, 
refer to chapter 5, which explains how to 
use the loader. 



This cataloged procedure, shown in Figure 
11-6, comprises two procedure steps, LKED 
and GO, which are similar to the procedure 
steps of the same names in PLIXCLG. 

In the procedure step LKED, the DD 



Load and Execute (PLIXG) 

This cataloged procedure, shewn in Figure 
11-8, achieves the same results as PLIXLG 
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//PLIXCG PROC LKLBDSN='SYSl.PLIBASE* 

//PLI EXEC PGM=IELOAA, PARM=' OBJECT ,NODECK» ,REGION=100K 

//SYSPRINT DD SYSOUT=A, DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSLIN DD DSN=S6LOADSET ,DISP= (MOD, PASS) ,UNIT=SYSSQ, 

// SPACE=( 80, (250,100)) 

//SYSUTl DD DSN=&6SYSUTl,UNIT=SYSDA,SPACE=(1024, (60, 60) , ,CONTIG) , 

// DCB=BLKSIZE=1024 

//GO EXEC PGM=LOADER, PARM='MAP, PRINT' ,REGION=100K, 

// COND=(9,LT,PLI) 

//SYSLIB DD DSN=gLKLBDSN,DISP=SHR 

// DD DSN=SYS1.PLIBASE,DISP=SHR 

//SYSLIN DD DSN=66LOADSET,DISP= (OLD, DELETE) 

//SYSLOUT DD SYSOUT=A 

//SYSPRINT DD SYSOUT=A 

Figure 11-7. Cataloged procedure PLIXCG 



//PLIXG PROC LKLBDSN='SYSl. PLI BASE' 

//GO EXEC PGM=LOADER,PARM= 'MAP, PRINT ',REGION=10 OK 

//SYSLIB DD DSN=£LKLBDSN,DISP=SHR 

// DD DSN=SYSl.PLIBASE,DISP=SHR 

//SYSLOUT DD SYSOUT=A 

//SYSPRINT DD SYSOUT=A 

Figure 11-8. Cataloged procedure PLIXG 



but uses the loader instead of the linkage 
editor. However, instead of using two 
procedure steps (link edit and execute), it 
has only one. In this procedure step, the 
loader program is executed. This program 
processes and executes an object module 
placed in the data set defined by a DD 
statement with the name SYSLIN; ycu must 
supply this statement with the qualified 
name GO. SYSLIN. 



The REGION parameter of the EXEC 
statement GO specifies 100K tyttes. Since 
the loader requires about 17K bytes of main 
storage, there are about 83K bytes for your 
program; if this is likely tc be 
insufficient, you must modify the REGION 
parameter. The use of the leader iirposes 
certain restrictions on your PL/I program; 
before using this cataloged procedure, 
refer to Chapter 5, which explains how to 
use the loader. 
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Chapter 12: Program Checkout 



Program checkout is the application of 
diagnostic and test processes to a program. 
You should give adequate attention to 
program checkout during the development of 
a program so that: 

• A program becomes fully operational 
after the fewest possible test runs, 
thereby minimizing the time and cost of 
program development. 

• A program is proved to have fulfilled 
all the design objectives before it is 
released for production work. 

• A program has complete and clear 
documentation to enable both operators 
and program maintenance personnel to use 
and maintain the program without 
assistance from the original programmer. 

The data used for the checkout of a program 
should be selected to test all parts of the 
program, whilst the data should be 
sufficiently comprehensive to provide a 
thorough test of the program, it is easier 
and more practical to monitor the behaviour 
of the program if the volume of data is 
kept to a minimum. 



Conversational Program Checkout 



The optimizing compiler can be used in 
conversational mode when writing and 
testing programs at a terminal. The 
conversational features are available to 
users where the TSO (Time Sharing option) 
facilities of the operating system are 
present. The conversational facilities 
enable you to enter a PL/I program from a 
terminal, through which you will receive 
diagnostic messages for the compilation. 
You can also communicate with the program 
during execution using PL/I files 
associated with the terminal. Thus a PL/I 
program can be checked out during its 
construction, thereby saving a substantial 
amount of elapsed time that can occur 
between test compilation and execution runs 
in batched processing. 

The PL/I program is entered and 
processed using the PLI , EDIT, and other 
commands and features described in the 
publication OS TSO: PL/I Optimizing 
compiler. 



Compile -time Checkout 



At compile time, both the preprocessor and 
the compiler can produce diagnostic 
messages and listings according to the 
compiler options selected fcr a particular 
compilation. The listings and the 
associated compiler options are discussed 
in Chapter 4. The diagnostic messages 
produced by the optimizing compiler are 
identified by a number prefixed "IEL". 
These diagnostic messages are available in 
both a long form and a short form. The 
long messages are designed to be as self- 
explanatory as possible. The short 
messages are designed for reproduction at a 
terminal when the compiler is being used in 
a TSO environment. The short messages are 
obtained by specifying the SMESSAGE 
compiler option. Each message is 
reproduced in the publication: OS PL/ I 
Optimizing Compiler Messages . This 
publication includes explanatory notes, 
examples, and any action to be taken. 

Always check the compilation listing for 
occurrences of these messages to determine 
whether the syntax of the program is 
correct. Messages of greater severity than 
warning (that is, error, severe error, and 
unrecoverable error) should be acted upon 
if the message does not indicate that the 
compiler has been able to "fix" the error 
correctly. You should appreciate that the 
compiler, in making an assumption as to the 
intended meaning of any erroneous statement 
in the source program, can introduce a 
further, perhaps more severe, error which 
in turn can produce yet another error, and 
so on. When this occurs, the result is 
that the compiler produces a number of 
diagnostic messages which are all caused 
either directly or indirectly by the one 
error. 

Other useful diagnostic aids produced by 
the compiler are the attribute table and 
cross-reference table. The attribute table, 
specified by the ATTRIBUTES option, is 
useful for checking that program 
identifiers, especially those whose 
attributes are contextually and implicitly 
declared, have the correct attributes. The 
cross-reference table is requested by the 
XREF option, and indicates, for each 
program variable, the number of each 
statement that refers to the variable. 

To prevent unnecessary waste of time and 
resources during the early stages of 
developing programs, use the NOOPTIMIZE,, 



Chapter 12: Program Checkout 157 



NOSYNTAX, and NOCOMPILE options. The 
NOOPTIMIZE option will suppress 
optimization unconditionally, and the 
remaining options will suppress 
compilation, link editing, and execution 
should the appropriate error conditions be 
detected. 

The NOSYNTAX option specified with the 
severity level "W", "E", or "s" will cause 
compilation of the output from the PL/I 
preprocessor, if used, to be suppressed 
prior to the syntax- checking stage should 
the preprocessor issue diagnostic messages 
at or above the severity level specified in 
the option. 

The NOCOMPILE option specified with the 
severity level "W", "E", or "S" will cause 
compilation to be suppressed after the 
syntax-checking stage if syntax checking or 
preprocessing causes the compiler to issue 
diagnostic messages at or above the 
severity level specified in the option. 



identified by the prefix "I EM". The 
messages are always printed on the SYSPRINT 
file. 

A failure in the execution of a PL/I 
program could be caused by one of the 
following: 

Logical errors in source programs. 

Invalid use of PL/I. 

Unforeseen errors. 

Operating error. 

Invalid input data. 

Unidentified program failure. 

A compiler or library subroutine 
failure. 

System failure. 



Linkage Editor Checkout 



Logical Errors in Source Programs 



When using the linkage editor, check 
particularly that any required overlay 
structuring and incorporation of additional 
object and load modules have been performed 
correctly. Diagnostic messages produced by 
the linkage editor are prefixed "IEW". 
These messages are fully documented in the 
publication: OS Linkage Editor and Loader . 

When checking the processing performed 
by the linkage editor, refer to the module 
map produced by the linkage editor showing 
the structure of the load module. The 
module map names the modules that have been 
incorporated into the program. The 
compiler produces an external symbol 
dictionary (ESD) listing if requested by 
the ESD option. The ESD listing indicates 
the external names that the linkage editor 
is to resolve in order to create a load 
module. The linkage editor is described in 
Chapter 5. 



Execution-time Checkout 



At execution time, errors can occur in a 
number of different operations associated 
with running a program. For instance, an 
error in the use of a job control statement 
can cause a job to fail. Most errors that 
can be detected are indicated by a 
diagnostic message. The diagnostic 
messages for errors detected at execution 
time are also listed in the messages 
publication for this compiler and 



Logical errors in source programs can often 
be difficult to detect. Such errors can 
sometimes cause a compiler cr library 
failure to be suspected. The more common 
errors are the failure to convert correct ly 
from arithmetic data, incorrect arithmetic 
operations and string manipulation 
operations, and failure to match data lists 
with their format lists. 



Invalid Use of PL/I 



It is possible that a misunderstanding of 
the language, or the failure to provide the 
correct environment for using PL/I, results 
in an apparent failure of a PL/I program. 
For example, the use of uninitialized 
variables, the use of controlled variables 
that have not been allocated, reading 
records into incorrect structures, the 
misuse of array subscripts, the misuse of 
pointer variables, conversion errors, 
incorrect arithmetic operations, and 
incorrect string manipulation operations 
can cause this type of failure. 



Unforeseen Errors 



If an error is detected during execution of 
a PL/I program in which no on-unit is 
provided to terminate execution or attempt 
recovery, the job will be terminated 
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abnormally. However, the status of a 
program executed in a batch-processing 
environment, at the point where the error 
occurred, can be recorded by the use of an 
ERROR on-unit that contains the statements: 

ON ERROR BEGIN; 
ON ERROR SYSTEM; 
PUT DATA; 
END; 

The statement ON ERROR SYSTEM; contained 
in the on-unit ensures that further errors 
caused by attempting to transmit 
uninitialized variables "do not result in a 
permanent loop. 



Operating Error 



A job could fail because of an operating 
error, such as running a job twice so that 
a data set becomes overwritten or 
erroneously deleted. Other operating 
errors include getting card decks into the 
wrong order and the failure to give 
operators correct instructions for running 
a job. 



Invalid Input Data 



A program should contain checks to ensure 
that any incorrect input data is detected 
before it can cause the program to fail. 

Use the COPY option of the GET statement 
if you wish to check values obtained by 
stream- oriented input. The values will be 
listed on the file named in the COPY 
option. If no file name is given, SYSPRINT 
is assumed. 



Unidentified Program Failure 



In most circumstances, an unidentified 
program failure should not occur when using 
the optimizing compiler. Exceptions to 
this could include the following: 

• When the program is executed in 
conjunction with non-PL/I modules, such 
as FORTRAN or COBOL. 

• When the program obtains, by means of 
record-oriented transmission, incorrect 
values for use in label, entry, locator, 
and file variables. 

• Errors in job control statements, 
particularly in defining data sets. 



If execution of a prograir terminates 
abnormally without an accompanying PL/I 
execution-time diagnostic message, it is 
probable that the error that caused the 
failure also inhibited the production of a 
message. In this situation, it is still 
possible to check the PL/I scurce program 
for errors that could result in overwriting 
areas of the main storage region that 
contain executable instructions, 
particularly the communications region, 
which contains the address tables for the 
execution-time error -hand ling routine. 
These errors may also be present in modules 
compiled by the checkout coir filer with 
NODIAGNOSE and COMPATIBLE and executed in 
conjunction with the modules produced by 
the optimizing compiler. The types of PL/I 
program that might cause the main storage 
to be overwritten erroneously are: 

• Assignment of a value to a non-existent 
array element. For example: 

DCL ARRAY (10); 



DO I = 1 TO 100; 
ARRAY (I) = VALUE; 

To detect this type of error in a module 
compiled by the optimizing compiler, 
enable the SUBSCRIPTRANGE condition. 
For each attempt to access an element 
outside the declared range of subscript 
values, the SUBSCRIPTRANGE condition 
will be raised. If there is no on-unit 
for this condition, a diagnostic message 
will be printed and the ERROR condition 
raised. This facility, although 
expensive in execution time and storage 
space, is a valuable program-checkout 
aid. 

• The use of incorrect locator values for 
locator (pointer and offset) variables. 
This type of error is possible if a 
locator value is obtained by means of 
record-oriented transmission. Check 
that locator values created in a 
program, transmitted to a data set, and 
subsequently retrieved for use in 
another program, are valid for use in 
the second program. 

An error could also be caused by 
attempting to free a non-based variable. 
This could be caused by freeing a based 
variable when its qualifying pointer 
value has been changed. For example: 

DCL A STATIC, B BASED (P); 
ALLOCATE B; 
P = ADDR(A); 
FREE B; 

• The use of incorrect values for label. 
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entry, and file variables. Errors 
similar to those described above for 
locator values are possible for label, 
entry, and file values that are 
transmitted and subsequently retrieved. 

The use of the SUBSTR pseudovariable to 
assign a string to a position beyond the 
maximum length of the target string. 
For example: 

DCL X CHAR (3) ; 

1=3; 

SUBSTR(X,2 f I) = 'ABC; 

The STRINGRANGE condition can be used to 
detect this type of error in a module 
compiled by the optimizing compiler. 



Compiler or Library Subroutine Failure 



If you are absolutely convinced that the 
failure is caused by a compiler failure or 
a library subroutine failure, you should 
notify your management, who will initiate 
the appropriate action to correct the 
error. This could mean calling in IBM 
personnel for programming support to 
rectify the problem. Before calling IBM 
for programming support, refer to the 
instructions for providing the correct 
information to be used in diagnosing the 
problem. These instructions are given in 
Appendix C, "Requirements for Problem 
Determination and APAR Submission." 
Meanwhile, you can attempt to find an 
alternative way to perform the operation 
that is causing the trouble. A bypass is 
often feasible, since the PL/I language 
frequently provides an alternative method 
of performing a given operation. 



System Failure 



System failures include machine 
malfunctions and operating system errors. 
These failures should be identified to the 
operator by a system message. 



Statement Numbers and Tracing 



The compiler FLOW option provides a 
valuable program- checkout aid. The 
FLOW(n,m) option creates a table of the 
numbers of the last "n" branch-out and 
branch-in statements, and the last "m" 
procedures and on -units to be entered. (A 
"branch-out" statement is a statement that 
transfers control to a statement other than 



that which immediately fellows it, such as 
a GOTO statement. A branch- in statement is 
a statement that receives control frcm a 
statement other than that which immediately 
precedes it, such as a PROCEDURE, ENTRY, or 
any other labeled statement.) The figure 
you choose for "n" should be large enough 
to provide a usable trace of the flow of 
control through the program. 
Alternatively, if you do not specify the 
FLOW option explicitly, defaults for the 
FLOW option will be used. 

The trace table can be obtained by any 
of the methods described be lew. 

The trace is printed whenever an on-unit 
with the SNAP option or a PUT ALL statement 
is encountered, it gives both the statement 
numbers and the names of the containing 
procedures or on-units. For example, an 
ERROR on-unit that results in both the 
listing of the program variables and the 
statement number trace can be included in a 
PL/ I program as follows: 

ON ERROR SNAP BEGIN; 
ON ERROR SYSTEM; 
PUT DATA; 
END; 

A flow trace can be specified as part of 
the output from the PL/I dump facility 
PLIDUMP, discussed later in this chapter. 



Dynamic Checking Facilities 



It is possible for a syntactically-ccrrect 
program to produce incorrect results 
without raising any PL/I error conditions. 
This can be attributed to the use of 
incorrect logic in the PL/I source program 
or to invalid input data. Detection of 
such errors from the resultant output (if 
any) can be a difficult task. It is 
sometimes helpful to have a record of each 
of the values assigned to a variable, 
particularly label, entry, loop control, 
and array subscript variables. This can be 
obtained by using the CHECK prefix option. 
Note that, unless care is exercised, the 
indiscriminate use of the facilities 
described below will result in a flood of 
unwanted and unusable printout. 

A CHECK prefix option can specify 
program variables in a list. Whenever a 
variable that has been included in a check- 
list is assigned a new value, the CHECK 
condition is raised. The standard system 
action for the CHECK condition is to print 
the name and new value of the variable that 
caused the CHECK condition to be raised. 
An example of a CHECK prefix options list 
is: 
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(CHECK(A,B,C,L)):/* CHECKOUT PREFIX LIST */ 
TEST: PROCEDURE OPTIONS (MAIN) ; 
DECLARE A etc. , 



The standard system action for the 
FINISH condition in batched processing is 
to terminate the task, and, in 
conversational processing, tc give control 
to the terminal. 



If the CHECK condition is to be raised 
for all the variables used in a program, 
the CHECK prefix option can be more simply 
specified without a list of items. For 
example: 

(CHECK) : TEST: PROCEDURE; 



Control of Exceptional Conditions 



During execution of a PL/I object program, 
a number of exceptional conditions can be 
raised, either as a result of program- 
defined action, or as a result of exceeding 
a hardware limitation. PL/I contains 
facilities for detecting such conditions. 
These facilities can be used to determine 
the circumstances of an unexpected 
interrupt, perform a recovery operation, 
and permit the program to continue to run. 
Alternatively, the facilities can be used 
to detect conditions raised during normal 
processing, and initiate program- defined 
actions for the condition. Note that some 
of the PL/I conditions are enabled by 
default, some cannot be disabled, and 
others have to be enabled explicitly in the 
program. Refer to the language reference 
manual for this compiler for a full 
description of each condition. 

Note that the SIGNAL statement can be 
used to raise any of the PL/I conditions. 
Such use permits any on-units in the 
program to be tested during debugging. 

The standard system action for the ERROR 
condition for which there is no on-unit, 
is, in batched processing, to raise the 
FINISH condition, and in conversational 
processing, to give control to the 
terminal. The FINISH condition is also 
raised for the following: 

• When a SIGNAL FINISH statement is 
executed. 

• When a PL/ I program completes execution 
normally. 

• On completion of an ERROR on-unit that 
does not return control to the PL/I 
program by means of a GOTO statement. 

• when a STOP statement is executed or 
when an EXIT statement is executed in a 
major task. 



Use of the PL/I Preproces so r in Program 
Checkout 



During program checkout, it is often 
necessary to use a number of the PL/I 
conditions (and the on-units associated 
with them) and subsequently to remove them 
from the program when it is found tc be 
satisfactory. The PL/I preprocessor can be 
used to include a standard set of program- 
checkout statements from the source 
statement library. When the program is 
fully operational, the ^INCLUDE statement 
can be removed, and the resultant object 
program compiled for execution. 

A standard set of PL/l program checkout 
statements would include both the enabling 
of any conditions that are disabled by 
default and the provision of the 
appropriate on-units. The %INCLUDE 
statement that causes the inclusion of the 
set of program checkout statements wculd 
usually be placed after any on-units that 
must remain in the program permanently in 
order to cancel their effect during program 
checkout. 



On-Codes 



On-codes can indicate more precisely what 
type of error has occurred where a 
condition can be raised by rrcre than one 
error. For example, the ERROR condition 
can be raised by a number of different 
errors, each of which is identified by an 
on-code. you can obtain the cn-ccde by 
using the condition built-in function 
ONCODE in the on-unit. The cn-ccdes are 
described in the language reference manual 
for this compiler. 



Dumps 



Should the checks given above fail to 
reveal the cause of the error, it may be 
necessary to obtain a printout, or dump, of 
the main storage region used by the 
program. A dump can display the contents 
of all buffers associated with PL/I files, 
the PL/I file attributes for each file open 
when the dump is taken, and a trace cf the 
block invocations that occurred during 
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execution before the dump was taken. 



A hexadecimal dump can also be obtained 
to determine the machine instructions and 
data present in main storage when the 
failure occurred. The use of a hexadecimal 
storage dump requires a knowledge of 
assembler language programming and an 
understanding of object program 
organization. 

Refer to the execution logic manual for 
this compiler for information about the 
organization of the object programs 
produced by the optimizing compiler, and 
how to interpret a storage dump. 

To obtain a formatted PL/I dump, you 
must invoke the PL/I resident library dump 
module by calling PLIDUMP. Note that a DD 
statement with the ddname PLIDUMP or 
PLIDUMP must be supplied to define the data 
set for the dump. 

The data set defined by the PLIDUMP DD 
statement must have DSORG=PS specified or 
assumed by default, and must have one of 
the following attributes: 

• It must be allocated to SYSOUT. 

• It must be allocated to the terminal or 
unit-record device. 

• DISP=MOD must be specified. 

The page size of the PLIDUMP output is 
taken from the PAGESIZE field of PLITABS. 

PLIDUMP can be invoked with two optional 
arguments . The first argument is a 
character -string constant used to specify 
the types of information to be included in 
the dump. The second argument can be a 
character-string expression or a decimal 
constant with which you can identify the 
output produced by PLIDUMP. The format of 
the PLIDUMP statement is: 

CALL PLIDUMPE ( 'options-list" 

[ r user- identification] ) ] ; 

The options-list is a contiguous string 
of characters that may include the 
following: 

T To request a trace of active 

procedures, begin blocks, on-units, 
and library modules. 

NT To suppress the output produced by T 
above. 

F To request a complete set of 

attributes for all files that are 
open, and the contents of the buffers 
used by the files. 



NF To suppress the output produced by F 
above. 

S To request the termination of the 

program after the completion cf the 
dump. Note: The FINISH condition is 
not raised. 

C To request continuation of execution 
after completion of the dump. 

H To request a hexadecimal dump of the 
main storage partition used by the 
program. 

NH To suppress the hexadecimal dump. 

B If T is specified, to produce a 

separate hexadecimal duirp of control 
blocks such as the TCA and the ESA 
chain that are used in the trace 
analysis. If F is specified, to 
produce a separate hexadecimal dump of 
control blocks used in the file 
analysis, such as the FCB. 

NB To suppress hexadecimal dumps of 
control blocks. 

A To request information relevant to all 
tasks in a multitasking program. 

E To request that an exit be made from 
the current task of a multitasking 
program and that execution of the 
program continues after completion of 
the requested dump. 

To request information relevant only 
to the current task in a multitasking 
program. 

The defaults assumed for the above 
options not specified explicitly are: 

T F C A NH NB 

The user-identification permits ycu to 
specify a character-string expression or a 
decimal constant to identify individual 
dumps. It cannot be specified without the 
preceding argument in the argument list,. 



Trace Information 



Trace information produced by PLIDUMP 
includes a trace through all the active 
DSAs. (DSAs will be present for compiled 
blocks, such as procedures and on-units, 
and for library routines.) For on-units, 
the dump gives the values of any condition 
built-in functions that could be used in 
the on-unit, regardless of whether the on- 
unit actually used the condition built-in 
function. If a hexadecimal dump is also 
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Return 
Codes 

0000 

1-999 



1000 



2000 



4000 



4004 



4008 



4012 



4020 



4024 



Figure 12-1. 



Meaning 



Normal termination. 

Return codes available for use 
with PLIRETC. 

Code returned if a STOP 
statement, an EXIT statement, 
or a CALL PLIDUMP statement 
with the "E" or "S" option is 
executed, or if ISA3IZE is 
insufficient. This will be 
added to any PLIRETC value. 

Code returned if ERROR is 
raised and there is no ERROR 
or FINISH on-unit containing a 
GOTO statement. This value 
will be added to any PLIRETC 
value. 

Code returned if an interrupt 
occurs in the PL/I error 
handler or during program 
initialization. 

Code returned if the PRV 
(pseudo register vector) is 
too large. 

Code returned if PL/I program 
has no main procedure. 

Not enough main storage 
available. 

Code returned if the program 
is about to enter a permanent 
wait state. 

Code returned if a task in a 
multitasking program has 
terminated without use of the 
PL/ I termination routines. 

Return codes from 
execution of a PL/I 
program 



requested, the trace information will also 
include : 

• The address of each DSA (Dynamic Storage 
Area) . 

• The address of the TCA (Task 
Communications Area) . 

• The contents of the registers on entry 
to the PL/I error -handler module 
(IBMCERR) . 

• The PSW or the address from which the 



PL/I error handler module (IBMCERR) was 
invoked. 

• The addresses of the library module DSAs 
back to the most recently-used compiled 
code DSA. 

DSAs and the TCA are described in the 
execution logic manual for this compiler. 
A table of statement numbers indicating the 
flow of control through the program is 
always produced. 



File Information 



File information produced by PLIDUMP 
includes the default and declared 
attributes of all open files, and the 
contents of all buffers that are accessible 
to the dump routine. The information is 
given in BCD notation, and if hexadecimal 
output is also requested, in hexadecimal 
notation also. The address and contents of 
the FCB are then printed. 



Hexadecimal Dum p 



The hexadecimal dump is a duirp of the 
region of main storage containing the 
program. The dump is given as three 
columns of printed output. The left-hand 
and middle columns contain the contents of 
storage in hexadecimal notation. The third 
column contains a BCD translation of the 
first two columns. For hexadecimal 
characters that cannot be represented by a 
printable BCD character, a full stop is 
printed. 



Return Codes 



Both the compilation and the link editing 
of a PL/I program will result in a return 
code being passed to indicate the severity 
of any errors found. It is possible to 
pass a return code from a PL/I program, 
either for examination in a subsequent job 
step if execution of that step is 
conditional upon the value cf the cede 
returned, or merely to indicate conditions 
that were encountered during execution. 
Conditional execution of a job step is 
determined by use of the CONE parameter of 
the JOB or EXEC statement. 

Return codes can be set in a PL/ I 
program by passing as an argument to the 
CALL PLIRETC statement a code represented 
as a variable with the attributes FIXED 
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BINARY(31,0) . The range of codes used 
should be restricted to 1 through 999. If 
a return code of greater than 999 is 
specified, the return code is set to 999 
and a diagnostic message is issued. Codes 
higher than 999 are returned if an error 
causes the program to terminate. In some 
cases the return code for the program will 
be added to any code created by use of the 
CALL PLIRETC statement. In other cases it 
will overwrite any code set by use of the 
CALL PLIRETC statement. Other error 
situations, listed in Figure 12-1, will 
also cause a program- generated return code 
to be overwritten. 

If a return code in the 4 000-4024 range 
is encountered and the cause cannot be 
traced to a source program error, it may be 
necessary to call in IBM program support 
personnel. Appendix C, "Problem 
Determination and APAR Submission", 
describes the materials that will be 
required for examination by IBM in such 
circumstances . 



The ABEND Facility 



Standard system action when the ERROR 
| condition is raised and there is either no 
| ERROR on-unit, or an ERROR on- unit that 
| terminates normally (that is, one that does 



not contain a GOTO STATEMENT) is to 
terminate without issuing an AEENE. If the 
standard module IBMBEER in the PL/I 
resident library is altered as indicated 
below then the ABEND facility becomes 
(available. IBMBEER will be called whenever 
the PL/ I program is to be terminated as a 
| result of the ERROR condition having been 
raised. 



Altering the Standard Modul e IBMBEER 



A non-zero return should be set in 
register 15. The program termination 
modules IBMBPIT and IEMTPIT call IEMEEER 
and interrogate register 15 on return; a 
non-zero value causes an ABEND to be 
issued. The value in register 15 is 
passed as a parameter to the ABEND which 
allows the options of user completion code, 
dump, and STEP ABEND to be selected. 

When IBMBEER is called, the content of 
register 1 will be set as follows to 
signify whether or not there is an ERROR 
on-unit : 

positive - ERROR on-unit 
negative - no ERROR on-unit 

An example of a user-written IEMEEER 
module is shown in Figure 12-2. 



IBMBEERl 



IBMBEERA 



IERRB 



I 

DUMP 

STEP 

|USERC0D1 
JUSERCOD2 
JRETNCOD1 

I 
IRETNCOD2 



CSECT 

ENTRY 

USING 

EQU 

LTR 

BNM 

L 

BR 

EQU 

L 

BR 

* 

EQU 

EQU 

EQU 

EQU 

DC 

DC 

DC 

DC 

END 



IBMBEERA 

*,15 

* 

R1,R1 

ERRB 

15,RETNC0D1 

14 

* 

15,RETNCOD2 

14 

128 

64 

3 001 

3 002 

AL1 (DUMP+STEP) 

AL3(USERC0D1) 

AL1 (DUMP+STEP) 

AL3 (USERCOD2) 



CSECT NAME 

DEFINE ENTRY POINT 

ADDRESSABILITY 

ENTRY POINT 

BRANCH 

IF ON-UNIT 

SET RETURN CODE NON-ZERO 

RETURN 



128=DUMP, 0=NO DUMP 

64=STEP ABEND, 0=TASK ABEND 

USER COMPLETION CODES (MUST BE GREATER 

THAN AND LESS THAN 4096) 



Figure 12-2. Typical User-Written IBMBEER Module 
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Chapter 13: Linking PL/I and Assembler-Language Modules 



This chapter describes how to create 
programs that combine routines written in 
PL/I and assembler language* It explains 
how a PL/I program invokes an assembler- 
language routine and, conversely, how an 
assembler-language routine invokes a PL/I 
procedure. 

Before describing any of the linkages in 
detail, the chapter discusses the PL/I 
environment that must be preserved when 
invoking an assembler-language routine from 
PL/I, and which must be created when 
invoking a PL/ I procedure from an 
assembler -language routine. 



The PL/I Environment 



The PL/I environment is the term used to 
describe a number of control blocks created 
by routines that are provided by the OS 
PL/I Resident and Transient Libraries to 
satisfy the storage-management and error- 
handling requirements of a PL/I procedure. 

When a PL/I program invokes an 
assembler-language routine, the invoked 
routine must ensure that the PL/I 
environment is preserved. The PL/l 
environment is preserved by observing the 
standard IBM System/3 60 linkage 
conventions, which include the storing of 
register values in a save area, and by 
ensuring that the content of register 12 is 
not modified by the assembler routine if 
PL/I is to handle interrupts that occur 
during execution of the assembler routine. 
Register 13 must be set to the address of a 
new save area established by the assembler 
routine. 



ESTABLISHING THE PL/ I ENVIRONMENT 



points, PLISTART, PLICALLA, and PLICALLB; 
these are described later in this chapter. 



Use of PLIMAIN to Invoke a PL/I 



Procedure 



| Once IBMBPIR or IBMTPIR (with IBMBPII or 
IBMTPII) has created the environment, it 
transfers control to the PL/ I procedure 
whose address is contained in the compiler- 
generated control section PLIMAIN. 
Normally, after link editing, PLIMAIN will 
contain the entry point address of the 
first, or only, PL/I main procedure in the 
program. If the assembler- language routine 
is to invoke a PL/I procedure that is not 
the first, or only, main PL/I procedure in 
the program, it must insert in PLIMMN the 
address of the entry point of the procedure 
it is to invoke. The example in Figure 
13-1 shows how this is done. 

If there is no main procedure in the 
program, the assembler routine should 
contain an entry point called PLIMAIN at 
which is held the address of the entry 
point of the PL/I routine tc be invoked. 
The example in Figure 13-2 shows how the 
appropriate address is inserted into the 
location represented by the entry point 
PLIMAIN. If the assembler program does not 
include an entry point called PLIMAIN in 
these circumstances, a dummy module called 
PLIMAIN will be included frcir the OS PL/I 
Resident Library. 

Once the PL/I environment has been 
established, it can, as shown in the 
example in Figure 13-3, be preserved, and 
any PL/I procedure can be invoked 
subsequently by loading the address of its 
entry point into register 15 , and executing 
a branch-and-link-register instruction to 
it. 



The PL/ I environment is established by the 
OS PL/I Resident Library routine IBMBPIR 
and the OS PL/ I Transient Library routine 
IBMBPII for a non -multi tasking program and 
by IBMTPIR and IBMTPII for a multitasking 
program. An assembler- language routine 
that invokes a PL/I procedure for which the 
PL/ I environment has not been established 
can use one of three standard entry points 
to establish the environment. The routine 
| IBMBPIR or IBMTPIR (with IBMBPII or 
IBMTPII) is entered through a control 
section which has three standard entry 



PLISTART, PLICALLA, AND PLICALLB 



P LISTART ; PLISTART is used when the PL/I 
environment must be established for a PL/I 
procedure that can use for its dynamic 
storage as much of the available space in 
storage as it requires, or, alternatively, 
as much as is specified. This entry point 
is normally used when the PL/I procedure is 
invoked directly from the operating system. 
It enables an assembler routine tc pass to 
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LA 1,ARGLIST 

L 2, =V (PLIMAIN) CHANGE ADDRESS IN PLIMAIN 

L 3 r =V(MYPR0G) TO THAT OF 

ST 3,0(2) MYPROG 

L 15,=V(PLICALLA) 

BALR 14,15 



ARGLIST DC 
DC 
DC 



A(argl) 
X*80' 
AL3 (arg2) 



FIRST ARGUMENT PASSED TO MYPROG 
LAST ARGUMENT PASSED TO MYPROG 
Figure 13-1. Inserting a PL/I entry point address in PLIMAIN 



ENTRY PLIMAIN 

LA 1, ARGLIST 

L 2, =A( PLIMAIN) INSERT ADDRESS IN PLIMAIN 

L 3, =V (MYPROG) OF ENTRY TO 

ST 3,0(2) MYPROG 

L 15,=V(PLICALLA) 

BALR 14,15 



ARGLIST DC 
DC 
DC 

PLIMAIN DS 



A(argl) 
X*80' 
AL3 (arg2) 

F 



FIRST ARGUMENT PASSED TO MYPROG 
LAST ARGUMENT PASSED TO KYPRCG 



Figure 13-2. Establishing PLIMAIN as an entry in the assembler-language routine 



a PL/ I procedure a parameter field 
identical to that which can be specified in 
the PARM field of a JCL EXEC statement. 

PLICALLA : PLICALLA is used when the PL/I 
environment must be established for a PL/I 
procedure that can use for its dynamic 
storage as much of the available space in 
storage as it requires. 

PLICALLB ; PLICALLB is used when the PL/I 
environment must be established for a PL/ I 
procedure that can use for its dynamic 
storage only a specified amount of the 
available storage. PLICALLB can optionally 
specify where that storage is to begin. 

Further details and examples using 
PLISTART, PLICALLA, and PLICALLB are given 
later in this chapter. 



THE DYNAMIC STORAGE AREA (DSA) AND SAVE 
AREA 



Whenever a PL/I procedure is invoked, it 
requires for its own use a block of storage 
known as a dynamic storage area (DSA) . A 



DSA for a PL/I procedure consists of a save 
area for the contents of registers, a 
backchain address that points to the save 
area for the previous routine,, and storage 
for automatic variables and miscellaneous 
housekeeping items. 

An assembler routine invoked froir PL/I 
should take the following action to 
preserve the PL/I environment: 

• If the assembler routine is to use the 
PL/I err or -handler, it must store the 
contents of all registers in the 
existing PL/I DSA and establish its own 
save area in which the backchain address 
of the PL/I DSA must be stored. The 
first two bytes of the save area must be 
set to zero. The second word of the 
save area is the backchain address. The 
remainder of the save area would only be 
used by a routine invoked from the 
assembler routine or by the PL/I error- 
handler, if used, for saving the 
assembler routine's registers. 

• If the assembler routine is not tc use 
the PL/I error-handler and does not 
invoke a further function routine, the 
SPIE macro must be used to reset the 



166 OS PL/I Optimizing Compiler: Programmer's Guide 



//OPTl3#3 JOB 

//STEP1 EXEC HASMHCPARM.ASM^ 

//ASM. SYSLIN DD DSN=66LOADSET , 

// SPACE= (80, (200,100) 

//ASM. SYSIN DD * 

MYPROG CSECT 

ENTRY ASSEM 

STM 14,12,12(13) 

BALR 10,0 

USING *,10 



LOAD,NODECK' 

UNIT=2314 ,DISP= (NEW, PASS) , 

) ,DCB=BLKSIZE=80 



LA 


4,SAVEAREA 


ST 


13,4(4) 


ST 


4,8(13) 


LR 


13,4 



ESTABLISH SUPERVISOR REGISTERS 
ESTABLISH ADDRESSABILITY 

CURRENT SAVE AREA ADDRESS 
STORE CHAINBACK ADDRESS 
STORE CHAIN FORWARD ADDRESS 
STORE CURRENT SAVE AREA ADDRESS 



SR 



1,1 





L 


15,=V(PLICALLA) 


* 
* 


BALR 


14,15 


L 


13,4(13) 




L 


14,12(13) 




LM 


1,12,24(13) 




BR 


14 


* 








DC 


C ASSEM' 




DC 


ALK5) 


ASSEM 


EQU 


* 




STM 


14,12,12(13) 




BALR 


10,0 


% 


USING 


*,10 




LA 


0,104 




L 


1,76(13) 




ALR 


0,1 




CL 


0,12(12) 




BNH 


ENOUGH 




L 


15,116(12) 




BALR 


14,15 


ENOUGH 


EQU 


* 


* 


ST 


0,76(1) 


* 


ST 


13,4(1) 




ST 


1,8(13) 


$ 


MVC 


72(4,1), 72(13) 




LR 


13,1 




MVI 


0(13),X*80' 




MVI 


1(13) ,X , 00« 




MVI 


86(13), X^l' 




MVI 


87(13) ^'CO' 



SR 



SR 



5,5 



1,1 



SET REGISTER 1 TO ZERO WHEN 
A PARAMETERLESS ENTRY POINT TO 
PROCEDURE THAT DOES NOT RETURN 
A VALUE IS TO BE INVOKED 

CALL THE PL/I PROCEDURE THAT 
HAS OPTIONS (MAIN) AND SO SET 
UP THE PL /I ENVIRONMENT AND 
THEN CALL ASSEM. 

ON RETURNING FROM PL/ 1 

RESTORE REGISTERS 

AND 

RETURN TO THE SUPERVISOR. 

THE NAME IN PI/I FORMAT 



STORE PL/ I REGISTERS 
FOR PROCEDURE "MAIN" 
ESTABLISH ADDRESSABILITY 
GET STORAGE FOR A NEW DSA 
LENGTH REQUIRED 104 BYTES 
ADDRESS OF START OF CURRENTLY - 
AVAILABLE STORAGE 
IS THERE ENOUGH SPACE LEFT? 
YES 

LOAD ADDR. OF OVERFLOW ROUTINE 
AND BRANCH TO IT. 

STORE ADDRESS OF START OF 

REMAINING AVAILABLE STORAGE 

IN NEW DSA AT OFFSET 76 

SET BACK CHAIN 

SET FORWARD CHAIN 

COPY ADDRESS OF WORKSPACE FOR 

USE BY THE PL/I LIBRARY 

POINT 13 AT NEW DSA 

SET FLAGS IN THE DSA TO 

PRESERVE PL/ I 

ERROR-HANDLING 

IN THE ASSEMBLER ROUTINE 

R5 MUST BE ZERO WHEN CALLING 
AN EXTERNAL PL/I PROCEDURE. 

SET REGISTER 1 TO ZERO WHEN 
A PARAMETERLESS ENTRY POINT TO 
PROCEDURE THAT DOES NOT RETURN 
A VALUE IS TO BE INVOKED 



Figure 13-3. (Part 1 of 2). Invoking PL/I procedures from an assembler routine 
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L 15 f =V(HEAD) 

BALR 14,15 



* 






LOOP 


EQU 
LA 
L 
BALR 


* 

1,ARGTLST1 
15,=V(PLIN) 
14,15 




L 
LTR 

BM 


3 , RESULT 

3,3 

OUTLOOP 



LA 1,ARGTLST2 

L 15,=V(PLOUT) 

BALR 14,15 

B LOOP 



CALL PL/ 1 TO •HEAD' PAGE 



CALL PL/I TO READ AND ADD 



TEST RESULT AND 

BRANCH OUT IF IT IS NEGATIVE. 



CALL PL/ I TO OUTPUT RESULT 



OUTLOOP EQU 
SR 



1,1 

L 15,=V(FOOT) 

BALR 14,15 



L 

LM 
BR 



13,4(13) 

14,12,12(13) 

14 



SET REGISTER 1 TO ZERO 
CALL PL/I TO 'FOOT' PAGE 



RETURN TO THE PL/ I PROC WITH 
OPTIONS (MAIN) . 



ARGTLSTl DC A (DATA) 

ARGTLST2 DC X'80' 

DC AL 3 (RESULT) 

DATA DC F'123' 

RESULT DC F'O' 

SAVEAREA DC lSF'O' 

END MYPROG 
/* 

//STEP2 EXEC PLIXCLG 
|//PLI.SYSIN DD * 

* PROCESS; 

| MAIN: PROC OPTIONS (MAIN) ; 
DCL ASSEM ENTRY; 
CALL ASSEM; 
END; 

* PROCESS; 

PLIN: PROC(I) RETURNS(FIXED BIN(3D); 

DCL (I, J) FIXED BIN (31) ; 

GET LIST (J) ; 

RETURN (1+ J); 
HEAD: ENTRY; 

PUT LIST ('THE FIRST LINE OF OUTPUT AT THE TOP OF THE PAGE') 
PAGE ; 

PUT SKIP (2) ; 

END; 

* PROCESS; 
PLOUT: PROC(K); 

DCL K FIXED BIN ( 31) ; 

PUT LIST(K) ; 

RETURN; 
FOOT: ENTRY; 

PUT LIST ('END OF THE OUTPUT FOR THIS JOB') SKIP (2) ; 

END; 
/* 
//GO.SYSIN DD * 

50 77 123 234 345 456 -23 -100 -123 -234 
/* 

Figure 13-3. (Part 2 of 2). Invoking PL/I procedures from an assembler routine 
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STM 14,11,12(13) 

BALR 10,0 

USING *,10 

LA 4,SAVEAREA 

ST 13,SAVEAREA+4 

LA 13,SAVEAREA 



STORE PL/I REGISTERS IN PL/I DSA 
ESTABLISH BASE REGISTER 



STORE PL/ I DSA ADDRESS IN SAVE AREA 
LOAD SAVE AREA ADDRESS 

ASSEMBLER 
ROUTINE 



L 13,4(13) RESTORE PL/I REGISTERS 

LM 14,11,12(13) AND 
BR 14 RETURN TO PL/I 

SAVE AREA DC 2 0F'0' ALLOCATE 80 BYTE SAVE AREA 

Figure 13-4. Invoking a non-recursive and non- reentrant assembler routine 



interrupt handler but only those 
registers that it modifies must be 
stored. The SPIE macro is discussed 
later in this chapter. 

The amount of storage allocated for a 
save area or DSA must be a multiple of 
eight bytes. The address of the next 
available block of storage following the 
save area or DSA must be stored at offset 
76 of that save area or DSA. This address 
is obtained by adding the address of the 
save area of DSA to its length. 



Calling Assembler Routines from PL/I 



INVOKING A NON-RECURSIVE AND NON- 
REENTRANT ASSEMBLER ROUTINE 



When a PL/I program invokes a non-recursive 
and non-reentrant assembler -language 
routine, the assembler-language routine 
must follow system/36 linkage conventions 
and save the registers for use by PL/I on 
return from the assembler-language routine. 
The register values are stored in the PL/I 
DSA, the address of which is contained in 
register 13 on entry to the assembler- 
language routine. This address must then be 
stored in the backchain word in a save area 
defined by the assembler routine itself. 
The appropriate assembler instructions 
should be executed immediately the 
assembler routine is invoked in order to 
achieve the given objectives. Before 
returning to the PL/I routine, the 
assembler routine must restore the 
registers to the values held when the PL/I 
routine invoked the assembler routine. The 
example in Figure 13-4 assumes that the 
assembler routine uses register 10 as its 
base register. 



INVOKING A RECURSIVE OR REENTRANT 
ASSEMBLER ROUTINE 



A recursive or reentrant assembler routine 
invoked from PL/I can use the PL/I storage 
overflow routine to attempt to obtain 
further storage when the storage initially 
available for dynamic use by the program is 
used up. 

A DSA established by the assembler 
| routine must have its first two bytes set 
to X'00* if it is to handle any program 
interrupts, such a DSA must be at least 80 
bytes in length to accommodate both the 
save area and two fullwords required by 
PL/ I for its housekeeping. If the PL/I 
error-handler is to service any program 
interrupts in the assembler- language 
routine, the DSA should be at least 88 
| bytes in length. The first byte of the DSA 
j should be set to X'80', the second byte set 
|to X'OO", and bytes 87 and 88 (the PL/T 
error-handler enable cells) set to X'^JICO*. 
In addition, a DSA can be as lcng as is 
needed to store any values that are to be 
preserved for use by a particular 
invocation. Note that a DSA obtained in 
this way must be a multiple cf 8 bytes in 
length. 

Termination of a recursive or reentrant 
assembler-language routine will release its 
DSA and cause control to be returned to the 
invoking routine. 

The example in Figure 13-5 shows how to 
create and release a DSA in a recursive or 
reentrant assembler routine. 



USE OF REGISTER 12 



If an assembler routine that modifies 
register 12 is to be invoked by a PI/I 
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ENOUGH 

* 
* 

* 



STM 14,11,12(13) 

BALR 10 , 

USING *,10 

LR 4,1 

LA 0,96 

L 1,76(13) 

ALR 0,1 

CL 0,12(12) 

BNH ENOUGH 

L 15,116(12) 

BALR 14,15 

EQU * 

ST 0,76(1) 

ST 13,4(1) 

MVC 72 (4,1) ,72(13) 

LR 13,1 

MVI 0(13),X'80' 

MVI 1(13),X'00' 

MVI 86(13) ,X' 91' 

MVI 87(13),X'C0' 



L 13,4(13) 

LM 14,11,12(13) 

BR 14 



STORE CALLER'S REGISTERS IN CALLERS DSA 
ESTABLISH BASE REGISTER 

SAVE ANY PARAMETER LIST ADDRESS 

PASSED FROM CALLING ROUTINE 

PUT THE LENGTH OF THE REQUIRED DSA IN REG 

LOAD THE ADDRESS OF THE NEXT AVAILABLE 

BYTE OF STORAGE AFTER THE CURRENT DSA 

ADD ADDRESSES 

COMPARE RESULT WITH ADDRESS OF LAST AVAILABLE 

BYTE IN STORAGE THAT CAN BE USED 

LOAD AND BRANCH TO THE PL/ I STORAGE OVERFLOW 
ROUTINE TO ATTEMPT TO OBTAIN MORE STORAGE 

STORE THE ADDRESS OF THE NEXT AVAILAELE 
BYTE IN STORAGE AFTER THE NEW DSA 
STORE THE CHAIN-BACK ADDRESS OF THE PREVIOUS 
DSA IN THE CURRENT DSA 

COPY ADDRESS OF LIBRARY 
WORKSPACE 

STORE THE ADDRESS OF THE NEW DSA IN REGISTER 13 
SET FLAGS IN DSA TO 
PRESERVE PL/ I 
ERROR-HANDLING 
IN THE ASSEMBLER ROUTINE 

ASSEMBLER 
ROUTINE 

RELEASE CURRENT DSA 
RESTORE CALLER'S REGISTERS 



Figure 13-5. Invoking a recursive or reentrant assembler routine 



procedure, any program-check interrupts 
will result in an unpredictable program 
failure unless the routine establishes its 
own error handling for program- check 
interrupts. Consequently, the routine 
should be amended to use a register other 
than register 12 so that the PL/I error- 
handler can be used, or it can issue a 
supervisor SPIE or STAE macro to establish 
its own program interrupt or abnormal 
termination handling facilities. The 
routine must subsequently restore PL/I 
error-handling facilities before returning 
to PL/I. This is discussed further in 
"Overriding and Restoring PL/ I Error- 
handling in an Assembler-language Routine" 
later in this chapter. (A routine that 
changes the content of register 12 should 
also store it on entry and restore it on 
return. ) 



Calling PL/ 1 Procedures from Assembler 
Language 

The simplest way to invoke a single 
external PL/I procedure from an assembler- 



language routine is to give the PL/I 
procedure the MAIN option and invcke it 
using entry point PLICALLA. All that is 
required is to load the address of PLICALLA 
into register 15 and then to branch and 
link to it. When PLICALLA is used in this 
way, the PL/I environment is created and 
control is then passed by way of PLIMAIN to 
the first (or only) irain PL/I procedure in 
the program. Use of this technique will 
cause the PI/I environment tc be 
established separately for each invocation. 



ESTABLISHING THE PL/I ENVIRONMENT FOR 
MULTIPLE INVOCATIONS 



If the assembler routine is to invoke 
either a number of PL/I routines cr the 
same PL/I routine repeatedly, the creation 
of the PL/I environment for each invccaticn 
will be unnecessarily inefficient. The 
solution is to create the PL/I environment 
once only for use by all invccaticns of 
PL/ I procedures. This can be achieved by 
invoking a main PL/I procedure which 
immediately reinvokes the assembler 
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routine. The assembler routine must 
preserve the PL/I environment and is then 
able to invoke any number of PL/I 
procedures directly. The example in figure 
13-3 contains an assembler-language routine 
that establishes the PL/ I environment once 
only for multiple invocations of PL/I 
procedures . 

In this example, the assembler routine 
MYPROG receives control initially from the 
supervisor, and invokes the PL/I main 
procedure MAIN using the entry point 
PLICALLA to the PL/I initialization 
routine. The PL/I procedure MAIN 
immediately reinvokes the same assembler 
routine at the entry point ASSEM. Note 
that, in this example, this name must be an 
odd number of characters to ensure that the 
next instruction is halfword aligned. At 
this entry point, the PL/I environment is 
stored, and a new DSA, 10 4 bytes in length, 
is created in a manner similar to that 
previously given for creating a DSA in a 
recursive or reentrant assembler- language 
routine. If there is insufficient room for 
the new DSA, the PL/I overflow routine is 
invoked to attempt to obtain storage for 
the DSA elsewhere in storage. 

The instructions in the assembler 
routine following the label ENOUGH through 
to the instruction that loads the address 
of the PL/I entry point HEAD are concerned 
with setting up the DSA so that the correct 
environment exists when the routine invokes 
the external PL/ I procedures PLIN and PLOUT 
and the secondary entry points within them. 
These instructions should always be present 
in order to preserve the PL/ I environment 
set up by the main procedure for subsequent 
use by any assembler-invoked PL/I 
procedures. 

Note that when an external PL/I 
procedure is invoked, register 5 must be 
set to zero, and that a PL/I procedure, 
such as PLIN in this example, that returns 
a value will assign the value to the last 
address in the argument list, ARGTLST1. 
This address is the address of the 
assembler-defined storage for RESULT . The 
constant X'80' in the first byte of the 
fullword containing the address of RESULTS 
in ARGTLSTl indicates that it is the last 
fullword in the argument list. 

If an assembler-language routine invokes 
a PL/I procedure without passing any 
parameters to it and without expecting any 
value to be returned from it, register 1 
must be set to zero. In this example, the 
procedure PLIN contains a RETURN 
(expression) statement, but when invoked 
through the parameterless entry point HEAD, 
does not return a value to the invoking 
routine. Similarly, the procedure PLOUT 
contains the parameterless entry point FOOT 



and does not return a value. 



ESTABLISHING THE PL/I ENVIRONMENT 
SEPARATELY FOR EACH INVOCATION 



If it is necessary to reestablish the PL/ I 
environment each time a PL/I procedure is 
invoked, use the entry point PLISTART, 
PLICALLA, or PLICALLB to invoke the PL/I 
initialization routines. The three entry 
points are used as follows: 

For PLISTART, the assembler language 
routine must insert in register 1 the 
address of a fullword which in turn 
contains the address of a halfword prefix 
to a character string. The character 
string, which must start on a fullwcrd 
boundary, can contain a parameter string 
similar to that which can be specified in 
the PARM field of a JCL EXEC statement? for 
example, 'ISASIZE (4K) ^/INPUT' . The 
halfword prefix must contain the number of 
characters in the string. This entry point 
is useful when a PL/I routine is "attached" 
by an assembler routine, because the entry 
point of the FL/I routine dees net have to 
be changed. The use of PLISTART is 
illustrated in Figures 13-6 and 13-7. 

For PLICALLA, the asseirbler-language 
routine must insert in register 1 the 
address of the argument list that ccntains 
the addresses of any arguments to be passed 
to the PL/ I procedure. 

For PLICALLB, the assembler-language 
routine must insert in register 1 the 
address of an argument list that contains 
the following: 

• The address of the argument list 
containing addresses to be passed to 
PL/I , and optionally, 

• The address of the length of storage to 
be made available to the program in* a 
non-multitasking program cr the irajor 
task in a multitasking program. The 
default for this length is half the 
available storage for a non-multitasking 
program or 8K bytes for the major task 
of a multitasking program. The length 

| of the initial storage area (ISA) passed 

| must be a multiple of eight bytes, so 

| that the ISA both starts and ends on a 

j double-word boundary. 

• The start address of the initial storage 
area (ISA) to be used by the PL/I 
program. This storage must be aligned 
on a double word. For further 
information, refer to the discussion of 
the ISASIZE option in Chapter 4. 
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LA 1,PLISTHWD GET PLIST ADDRESS 

ATTACH EP=PLIPROG ATTACH PL/I PROGRAM 



FLAG LAST WORD OF PLIST 



PLISTHWD DS OF 

DC X'80' 

DC AL3(PLISTHW) 

PLISTHW DC AL2(L' PLISTCH) LENGTH OF PARM STRING 

PLISTCH DC C'ISASIZE(8K) ,R/INPUT* PARM DATA 

Figure 13-6. Use of PLI START for ATTACH 





LA 


1, PLISTHWD 




L 


15 ,=V( PLI START) 


* 


BALR 


14,15 


* 


DS 


OF 


PLISTHWD 


DC 


X'80' 




DC 


AL3 (PLISTHW) 


PLISTHW 


DC 


H'O* 


PLISTCH 


DC 


AL2(0) 



GET PLIST ADDRESS 
GET PL/ I ENTRY POINT 
CALL PL/I ROUTINE 



FLAG LAST WORD OF PIIST 



NULL PARM STRING 
Figure 13-7. Use of PLISTART passing null parameter string 



Opti on 



Value 



REPORT 


X'80' 


NOREPORT 


X'40' 


SPIE 


X*20' 


NOSPIE 


X'10' 


STAE 


X'08* 


NOSTAE 


X*04» 


COUNT 


X'02 f 


NOCOUNT 


X'01* 


FLOW 


X f 80' 


NOFLOW 


X'40' 



in first byte 
in first byte 
in first byte 
in first byte 
in first byte 
in first byte 
in first byte 
in first byte 
in second byte 
in second byte 



Figure 13-8. Coding the options word 



The address of the length of storage to 
be made available to each of the 
subtasks in a multitasking program. The 
default for this length is 8K bytes for 
each subtask. This value is ignored for 
a non-multitasking program. The length 
of the ISA must be a multiple cf eight 
bytes. 

The address of the maximuir number of 
concurrent subtasks that can be attached 
at any one time. This value is ignored 
in a non-multitasking program. The 
default for this value is 20. 

The address of the options word, in 
which the execution- time options for a 
program compiled by the optimizing 



LA 1,ARGLIST 

L 15,=V(PLICALLA) 

BALR 14,15 



ARGLIST DC 
DC 



A(argl) 
A(arg2) 



ADDRESS OF FIRST ARGUMENT PASSED TO PL/I 
ADDRESS OF SECOND ARGUMENT PASSED TO PL/I 



DC X'80' END OF ARGUMENT LIST FLAG 

DC AL3(argn or return-value) ADDRESS OF LAST ARGUMENT 
* OR RETURNED VALUE 

Figure 13-9. Use of PLICALLA 
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ALIST 



ARGLIST 



* 

LENGTH 
ISA 
OPTIONS 



LA 1, ALIST 

L 15 ,=V (PLICALLB) 

BALR 14,15 



DC A (ARGLIST) 

DC A ( LENGTH) 

DC A ( ISA) 

DC A(0) 

DC A(0) 

DC X'80' 

DC AL3 (OPTIONS) 

DC A(argl) 

DC A(arg2) 

DC X*80' 

DC AL3 (argn or 

DC F'8192" 

DS 1024D 

DC X' 84000000* 



ADDRESS OF ARGUMENT LIST 
LENGTH OF STORAGE FOR PL /I 
ON DOUBLE WORD BOUNDARY 
ADDRESS OF ISA 
TASK ISA - NOT USED 

NUMBER OF CONCURRENT SUBTASKS - NONE 
END OF ARGUMENT LIST FLAG 
OPTIONS WORD 
ADDRESS OF FIRST ARGUMENT 
ADDRESS OF SECOND ARGUMENT 
END OF ARGUMENT LIST FLAG 
return-value) ADDRESS OF LAST ARGUMENT 
OR RETURNED VALUE 

ROUTINE'S STORAGE LIMITED TC 8K BYTES 
ROUTINES ISA STARTS HERE 
REPORT AND NOSTAE REQUESTED 



Figure 13-10. Use of PLICALLB 



compiler are specified. These options 
are: REPORT; STAE; SPIE; COUNT; and 
FLOW. They are described in Chapter 4. 
The hexadecimal value for each option is 
given in Figure 13-8. 



Note that the first byte in the last 
address word in each of these argument 
lists must contain X'80'. The examples in 
Figures 13-9 and 13-10 show the use of 
PLICALLA and PLICALLB to invoke the first 
(or only) main PL/I procedure in the 
program. The PL/I programs in these cases 
do not perform multitasking. 



If it is necessary to reestablish the 
PL/I environment for each invocation of a 
PL/I procedure that is not ,the first (or 
only) main procedure in the program, the 
user of either entry point PLICALLA or 
PLICALLB must insert in PLIMAIN the address 
of the appropriate entry point to the 
required PL/I procedure. The example in 
Figure 13-1 sets the address in pLIMAIN to 
that of the external entry name MYPROG. 



If it is necessary to reestablish the 
PL/I environment for each invocation of a 
PL/ I procedure where there is no main PL/I 
procedure in the program, the use of either 
entry point PLICALLA or PLICALLB must be 
accompanied by the use of an entry point 
called PLIMAIN in the assembler-language 
routine. This entry point must contain the 
address of the PL/I routine to be invoked. 
Figure 13-2 shows how this is inserted. 



PL/I Calling Assembler Callin g PL/I 



The information given in the preceding 
sections should be sufficient to write 
programs that include a PL/I procedure that 
invokes an assembler-language routine that 
invokes a further PL/I procedure. Figure 
13-3 contains an example of a program that 
performs this type of processing. 



Assembler Calling P L/I Calling 
Assembler 



The information given in the preceding 
sections should be sufficient to write 
programs that include an assembler-language 
routine that invokes a PL/I procedure that 
in turn invokes an assembler-language 
routine. Figure 13-3 contains an example 
of a program that performs this type of 
processing. 



Overriding and Restoring PL/I Error- 
handling 

An assembler -language routine invoked from 
PL/I can override PL/I error- handling by 
issuing its own SPIE macro tc handle 
program interrupts or STAE macro to handle 
abnormal terminations. If the SPIE macro is 
issued, the address of the PL/I PICA must 
be saved. A routine that cancels PL/I 
error -hand ling must restore the PL/ I error- 
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PROGA 


CSECT 






ENTRY 


ASSEM 




STM 


14, 12 r 12(13) 




BALR 


10 f 




USING 


*,10 




STAE 


(operands) 




SPIE 


(operands) 




ST 


1, SAVESPIE 




STAE 







L 


1, SAVESPIE 




SPIE 


MF=(E f (D) 




L 


13,4(0,13) 




LM 


1*4, 12, 12(13) 




BR 


14 


SAVESPIE 


DS 


A 



ENTRY-POINT INVOKED FROM PL/I 
STORE PL/I ENVIRONMENT 
ESTABLISH BASE REGISTER 

ESTABLISH NEW ABEND HANDLER 
ESTABLISH INTERRUPT HANDLER 
STORE OLD PICA ADDRESS 



RESTORE PL/ I ERROR HANDLING 
RESTORE PICA ADDRESS 

RESTORE PL/ I ENVIRONMENT 

RETURN TO PL/ I 



Figure 13-11. Method of overriding and restoring PL/I error- handling 



handling facilities before returning to the 
PL/ I program. It does this by issuing 
either a STAE macro with an operand of zero 
or an execute form of the SPIE macro 
restoring the saved PL/I PICA, according to 
the macros used to cancel the PL/ I error- 
handling. The example in Figure 13-11 
shows how these macros are used to cancel 
and subsequently restore PL/I error- 
handling. 



Arguments and Parameters 



Arguments are passed between PL/I and 
assembler routines by means of lists of 
addresses known as "parameter lists". Each 
address in a parameter list occupies a 
fullword in main storage. The last 
fullword in the list contains X'80' in its 
first byte to enable it to be recognized. 

Each address in a parameter list is 
either the address of a data item or the 
address of a control block that describes a 
data item. Data items themselves are never 
placed directly in parameter lists. 



RECEIVING ARGUMENTS IN AN ASSEMBLER- 
LANGUAGE ROUTINE 



When an assembler routine is invoked by a 
PL/I routine by means of a CALL statement 
or a function reference, the assembler 
routine will receive the address of a 
parameter list in register 1. The meaning 
of the addresses in the parameter list 
depends upon whether or not the entry point 
of the assembler routine has been declared 



with the ASSEMBLER option. These two cases 
are discussed separately in the following 
paragraphs. The ASSEMBLER option is fully 
described in the language reference itanual 
for this compiler. 



Assembler Routine Entry Point Declared 
with the ASSEMBLER Option 



The ASSEMBLER option is provided to 
simplify the passing of arguments from PL/I 
to assembler routines. It specifies that 
the parameter list set up by PL/I is to 
contain the addresses of actual data items, 
rather than the addresses of control 
blocks, irrespective of the types of data 
that are being passed. Thus if, for 
example, an array is passed from PL/I to an 
assembler routine, the address in the 
parameter list is that of the first element 
of the array. 

Note that if a particular data item is 
not byte-aligned (for example,, an unaligned 
bit string) , the address in the parameter 
list is that of the .byte that contains the 
start of the data item. Also, varying 
length character and bit strings are 
preceded in storage by a two-byte field 
specifying the current length of the 
string, and it is the address of this 
prefix that is placed in the parameter 
list. 

An assembler routine whose entry point 
has been declared with the ASSEMBLER option 
can be invoked only by means of a CALL 
statement. 
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Assembler Routine Entry Point Declared 
without the ASSEMBLER Option 



If the entry point of the assembler routine 
has not been declared with the ASSEMBLER 
option, each address in the parameter list 
is either the address of a data item or the 
address of a control block, depending on 
the type of data that is being passed. 

For arithmetic element variables, the 
address in the parameter list is that of 
the variable itself. For all other problem 
data types, the address in the parameter 
list is that of a control block known as a 
"locator/descriptor** . For program control 
data, the address in the parameter list is 
that of a control block. The formats of 
locator/descriptors and of control blocks 
for program control data are given in the 
execution logic manual for this compiler. 

It is recommended that the use of this 
type of linkage is avoided wherever 
possible. Access to locator descriptors is 
normally only necessary when the full 
attributes of the the arguments are not 
known by the assembler routine. The use of 
function references (which cannot be used 
with the ASSEMBLER option) can be avoided 
by passing the receiving field as a 
parameter to the assembler routine. 



be either the address of a data iteir or the 
address of a control block that describes a 
data item, depending upon the type cf data 
that is being passed. For arithmetic 
element variables, the address in the 
parameter list must be that of the of the 
variable itself. For all other problem 
data types, the address in the parameter 
list must be that of a lccatcr/descriptor. 
For program control data, the address in 
the parameter list must be that of a 
control block. The formats of locator 
descriptors and of control blocks fcr 
program control data are given in the 
execution logic manual fcr this ccirpiler. 

In some cases, it is possible to avoid 
the use of locator/descriptors when passing 
aggregates or strings by pretending that 
the data is an arithmetic variable. 
Suppose, for example, that an assembler 
routine is required to pass a fixed-length 
character string of twenty characters to a 
PL/I routine. The assembler routine can 
place the address of the character string 
itself in the parameter list, and the PL/I 
routine can be written thus: 

PP.-PROC(X); 

DC I X FIXED, 

A CHAR (20) BASED (P); 
P = ADDR(X); 



PASSING ARGUMENTS FROM AN ASSEMBLER- 
LANGUAGE ROUTINE 



In order to pass one or more arguments to a 
PL/I routine, an assembler routine must 
create a parameter list and set its address 
in register 1. The last fullword in the 
parameter list must have X*80* in its first 
byte. If the PL/I routine executes a 
RETURN (expression) statement, the last 
address in the parameter list must be that 
of the field to which PL/I is to assign the 
returned value. 

Each address in the parameter list must 



Because X is declared to be arithmetic, 
the address in the parameter list in 
interpreted as the start of the data that 
is being passed. This address is assigned 
to P, and is subsequently used as a locator 
for the based character string A, which has 
the attributes of the data that has 
actually been passed. 

This technique will work for all data 
types except unaligned bit strings. Note 
that the dummy arithmetic parameter need 
not have the same length as the data that 
is actually being passed; it is used simply 
to enable the the passed address to be 
identified as the start of the data. 
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Chapter 14: PL/ 1 Sort 



If you intend to use the PL/I sort 
facilities, the version of OS generated for 
your installation must include either a 
copy of the OS type 1 sort/merge program 

(Program Number 360S-SM-023) or a copy of 
the OS program product sort/merge program 

(Program Number 5734 SMl). The PL/I sort 
facilities make use of either OS sort/merge 
program to arrange records according to a 
predetermined sequence. 

Note ; If any of the data sets used by the 
sort program are to reside on an IBM 3330 
or IBM 3333 device, the OS program product 
sort/merge program (Program Number 5734 
SMI) must be used. 

The sort/ merge program includes user 
exit points to enable user-written routines 
to be entered at particular stages during 
the sorting operation and which provide 
access to records that are being sorted. 
The PL/I sort facilities provide an 
interface to enable the sort/merge program 
to be invoked and to call PL/I procedures 
through two of the user exits, E15 and E35. 

This chapter describes the method of 
invoking sort /merge from PL/I and the use 
of the user exits E15 and E35. It should 
| be used in conjuction with the relevant OS 
j Sort/Merge publication. The type 1 program 
jis described in OS Sort/Merge ; the program 
| product is described in the publications OS 
I Sort/Merge : Programmer ' s Guide and OS/VS 
I Sort/Merge : Programmer ' s Guide . These 
j books are referred to collectively 
| throughout the remainder of this chapter as 
| "the sort/merge publication". 



Storage Requirements 



The minimum storage requirements for the 
sort program when used in conjunction with 
a PL/I program compiled by the optimizing 
compiler is 12000 bytes or 26000 bytes in 
an MVT environment. Additional storage 
requirements exist if the sort program 
handles records that are greater than 400 
bytes in length and if it uses direct- 
access devices for input, output, or 
intermediate storage. Efficiency is 
enhanced if additional main storage can be 
| provided. Refer to the sort/merge 
j publication for further information. 



ENTRY NAMES 



A PL/ I program invokes the sort program by 
means of a CALL statement that naires one of 
four entry points to a PL/I sort interface 
subroutine provided by the OS PL/I Resident 
Library. The CALL statement also passes 
arguments that specify the requirements for 
the sorting operation. The arguments 
include a sequence of sort/merge control 
statements in the form of character-string 
expressions. The PL/I sort interface 
subroutine has entry points for four types 
of processing, shown in Figure 14-1. 



Entry 
Point 

PLISRTA 



PLISRTB 



PLISRTC 



PLISRTD 



Figure 14-1. 



Function 

Invokes the sort/merge program 
to retrieve records from a data 
set (SORTIN), sort them, and 
write them in sorted sequence 
onto another data set 
(SORTOUT). 

Invokes the sort/merge program 
and specifies the use of user 
exit E15. A PL/I procedure 
invoked at user exit El 5 will 
supply all the records to be 
sorted. The sorted records are 
written directly onto the data 
set SORTOUT. 

Invokes the sort/merge program 
and specifies the use of user 
exit E35. The sort/merge 
program retrieves records from 
the data set SORTIN. The 
sorted records are passed to a 
PL/I procedure invoked at user 
exit E35. This procedure will 
handle any output that is 
required. 

Invokes the sort/merge program 
and specifies the use of user 
exit E15 and user exit E35. 
The use of these user exits is 
exactly as described for 
PLISRTB and PLISRTC. 

Sort/merge program entry 
points 



After completion of the sort, the 
sort/merge program passes a return code to 
the invoking program to indicate whether 
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the sort is successful or not. The 
invoking procedure must include a variable 
with the attributes FIXED BINARY (31) to 
receive this return code, and the name of 
the variable must always be included in the 
argument list of the CALL statement that 
invokes sort/merge. The return codes and 
their meanings, are: 

sort successful 
16 sort unsuccessful 



converted into variable-length records and 
sorted. 

A PL/ I procedure invoked by way of a 
sort/merge user exit irust pass a return 
code to the sort program to indicate what 
action should be taken when the PL/ I 
procedure next relinquishes control. This 
is effected by invoking from within the 
procedure the PL/I library interface 
subroutine FLIRETC as follows: 

CALL PLIRETC (n) ; 



PROCEDURES INVOKED BY WAY OF SORT USER 
EXITS 



Both external and internal PL/I procedures 
can be invoked by way of sort user exits. 
The use of external PL/I procedures should 
present no problems so long as their entry 
names are declared in the main PL/I 
procedure and they are link edited with the 
main PL/I procedure to form a single 
executable program. 

All records passed to a PL/I procedure 
from the sort/merge program, and all 
records passed to the sort/merge program, 
must be in the form of character strings. 
A PL/ I procedure invoked by way of user 
exit E35 must include a character -string 
parameter; a PL/ I procedure invoked from 
user exit E15 must pass a record to the 
sort/ merge program by means of a RETURN 
statement with a character-string 
expression as its argument. 

Varying- length character strings can be 
returned from an El 5 exit procedure and 
sorted as variable- length records. 



where "n" can have one of the following 
values to specify the action required: 

For procedures invoked by means of user 
exit E15: 

8 Do not return to this procedure. 

12 Include the record returned frcrr 
the procedure in the sort. 

16 Stop the sort and return immediately 
to the invoking procedure. (OS 
program product sort/merge program 
only.) 

For procedures invoked by ireans cf user 
exit E35: 

4 Pass the next sorted record to the 
E35 procedure. 

8 Do not return to this procedure. 

16 Stop the sort and return iirirediately 
to the invoking procedure. (OS 
program product scrt/irerge program 
only.) 



Varying- length character strings cannot 
be received as parameters in an E35 exit 
procedure. However, a variable -length 
record passed to an E35 exit procedure can 
be declared as an adjustable -length 
character string. For example: 

E35X: PROC (VREC) ; 

DCL VREC CHAR(+); 



A sorting operation can also be 
specified to handle fixed-length records 
when the PL/I procedure is to pass varying - 
length character strings to it. In this 
situation, the strings are converted to 
fixed- length records of maximum length by 
having blanks added to them where 
necessary. 

Similarly, fixed-length character 
strings passed from a PL/I procedure can be 



DATA SETS USED BY SORT/MERGE 



The execution step for a PL/I program that 
uses PL/I sort requires job control DD 
statements for some or all cf the following 
data sets in addition to those required by 
the PL/I program. 



Input Data Sets 

If the sort/merge program is to read the 
records to be sorted from a data set, 
include a DD statement for the data set, 
using the ddname SORTIN. 
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Output Data Sets 



Arg. Description 

argl A character string containing the 
sort/merge SORT statement; this 
statement must be preceded and 
followed by a blank character. 

arg2 A character string containing the 
sort/merge RECORD statement; this 
statement must be preceded and 
followed by a blank character. 

arg3 Amount of main storage for the 
sort/merge program. 

arg4 Name of the variable in the 

invoking procedure that is to 
receive the sort return code. 

arg5 Entry point name of the PL/I 

procedure to be invoked from user 
exit E15. 

arg6 Entry point name of the PL/I 

procedure to be invoked from user 
exit E35. 

arg7 Replacement ddname characters (see 
the section "Multiple Invocations 
of Sort/Merge," later in this 
chapter) . 

arg8 Diagnostic message listing option 
(see the section "Sort/Merge 
Message Listing Options," later in 
this chapter) . 

arg9 Sorting technique option (see the 
section "Sort/Merge Sorting 
Techniques," later in this 
chapter) . 



If the sort/merge program is to write the 
sorted records onto an output data set, 
include a DD statement for the data set,, 
using the ddname SORTOUT. 



Other Data Sets 



For the sort program to execute 
successfully, it must have access to the 
following data sets: 

SORTLIB The system sort/irerge program 
library. 

SYSOUT For sort/merge program 
diagnostic messages. 

The following data sets are needed if 
the associated facility is to be used: 

SORTCKPT If the sort/merge program is to 
make use pf the 
checkpoint/restart facility. 

SYSUDUMP For dumps of main storage if 

required for debugging the sort 
program. 

PLIDUMP For dumps of main storage if 

required for debugging the PL/I 
program. 



Figure 14-2. 



Arguments used when 
invoking sort/merge 



Invoking Sort/Merge from PL/ 1 



Work Data Sets 



The sort/ merge program requires at least 
three magnetic- tape or direct -access data 
sets for use as intermediate storage; you 
can increase efficiency by specifying the 
direct-access data sets on separate direct- 
access devices. If the volume of records to 
be sorted demands more intermediate 
storage, you can specify up to 32 data 
sets. Provide a DD statement for each work 
data set, using the ddnames SORTWK01 to 
SORTWK32. 



The sort/merge program is invoked frcm a 
PL/I program by one of the CALL statements 
listed below. The number of arguments 
required depends on the entry name invoked. 

The arguments include sort/merge program 
control statements that define the 
processing to be carried out and describe 
the records to be sorted. (When the 
sort/merge program is invoked as an 
independent job step, these ccntrcl 
statements are submitted by way of the 
SYSIN input stream. ) The control 
statements are described in the sort/merge 
publication. Note that the MERGE statement 
cannot be used when invoking the scrt/merge 
program through the PL/I sort interface. 
The general syntax of the CALL statement 
for each of the four entry points is: 
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MSORT: PROC OPTIONS (MM N) ; 

/* INVOKE THE SORT PROGRAM FOR THE FIRST TIME */ 

CALL PLISRTA (' SORT FIELDS=( 7, 74 ,CH, A) ' , 

' RECORD TYPE=F,LENGTH=(80) *, 
100000, 
| RETURN CODE); 



/* INVOKE THE SORT PROGRAM FOR THE SECOND TIME */ 

CALL PLISRTA (' SORT FIELDS= (7, 74 ,CH,A) ' , 

' RECORD TYPE=F,LENGTH= (80) * , 

100000, 

RETURN_CODE f 

•TASK') ; 



END MSORT; 



Figure 14-3. 



Multiple invocations 
of sort/merge 



CALL PLISRTA (argl,arg2 ,arg3 ,arg4 ,arg7 , 
arg8,arg9) ; 

CALL PLISRTB(argl,arg2 ,arg3 ,arg4 ,arg5, 
arg7 ,arg8 ,arg9) ; 

CALL PLISRTC (argl , arg2 ,arg3 ,arg4 ,arg6 , 
arg7 , arg8 ,arg9) ; 

CALL PLISRTD (argl r arg2 r arg3 , arg4 , arg5 , 
arg6 r arg7 , arg8 ,arg9) ; 

The arguments are described in Figure 
14-2. 

| Arguments arg7, arg8 , and arg9 are 
| optional. If an optional argument is net 
used, it need not be specified unless 
another argument that follows it in the 
given order is specified.'- In this case, 
the unused argument must be specified as a 
null string. The following sections 
describe how to use the optional arguments, 



I Multiple Invocations of sort/Merg e 



invocations of the sort/merge program using 
modified ddnames, the optional argument 
should be a character string that contains 
the replacement characters. Note that the 
first character of the replacement string 
must be alphabetic. 



| For the invocation using the standard 
I sort/merge data sets, arg7 need not be 
| specified unless arg8 is specified, when 
|arg7 should be specified as a null string. 



j An example of multiple invocation is 
| given in Figure 14-3. 



In this example, the first invocation of 
the sort/merge program requires ED 
statements with the following ddnames: 

//SORTIN DD ... 
//SORTOUT DD ... 
//SORTWK01 DD . ... 



For multiple invocations of the sort/merge 
program from a single job step, the 
standard ddnames of sort data sets (SORTIN, 
SORTOUT, SORTWK, and SORTCKPT) can be 
changed by replacing up to the first four 
characters of the ddnames with a similar 
number of different characters. This is 
achieved by specifying the optional 
argument arg7 in the CALL statements that 
invoke the sort/merge program. For the 



The second invocation of the scrt/merge 
program requires DD statements with the 
following ddnames : 

//TASK IN DD ... 
//TASKOUT DD ... 
//TASKWK01 DD ... 
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I Sort/Merge Message Listing Options 



It is possible to select one of five 
options for specifying how the sort/ merge 
program diagnostic messages are to be 
produced. The selected option can be 
| specified as an optional argument (arg 8) 
to the entry point used. The optional 
argument should contain a character string 
selected from those given in Figure 14-4. 



NO No messages to be printed 

AP All messages to be printed on the 
printer 

AC All messages to be printed on the 
system console 

CP Critical messages only to be printed 
on the printer 

CC Critical messages only to be printed 
on the system console 

Figure 14-4. sort/merge message 
listing options 



| If no sort/merge listing option is 

I specified, the diagnostic messages will be 

(printed in the way specified when the 

I sort/merge program was generated. 

An example of a CALL PLISRTA statement 
that does not modify the sort/merge ddnames 
but that does specify a sort/merge program 
message listing option is given in Figure 
14-5. 



argument should contain cne cf the 
character strings BALN, CRCX , OSCL, cr POLY 
according to the technique that is 
required. 

| If no sorting technique cpticn is 
j specified, the ( sort/merge program will use 
| the method that is most efficient for the 
| particular job. Specifying that a 
(particular technique is to be used could 
(therefore cause the sort/merge operation to 
j be performed less efficiently. 

An example of a CALL PLISRTA statement 
that neither modifies sort/irerge ddnames 
nor specifies a sort/merge message listing 
option but that does specify a sorting 
technique is given in Figure 14-6. 



CALL PLISRTA (' SORT FIELDS= (7 f 74 ,CH,A) ' , 

' RECORD TYPE=F,LENGTH=(80) * , 

100000, 

RETURN_CODE, 
• t 

/* NULL DDNAME ARGUMENT */ 
t • 

/* NULL LISTING OPTION ARGUMENT /* 
•PCLY') ; 

Figure 14-6. Specifying a scrt/rcerge 
sorting technique option 



Examples of Using PL/ 1 Sort 



SORTING RECORDS DIRECTLY FROM ONE DATA 
SET TO ANOTHER (PLISRTA) 



CALL PLISTRA (' SORT FIELDS= (7 ,74 ,CH,A) ', 
' RECORD TYPE=F,LENGTH=(8 0) ', 
100000, 
RETURN_CODE, 

' • , /* NULL DDNAME ARGUMENT */ 
'CP') ; 

Figure 14-5. Specifying a sort/merge 
message listing option 



The example in Figure 14-7 illustrates the 
use of entry point PLISRTA to retrieve 
records from an input data set (SORTIN) , 
sort them, and write them directly in 
sorted sequence onto an output data set 
(SORTOUT) . 

The PL/I program contains the following 
elements: 



Sort/Merge Sorting Techniques 



It is possible to select one of four 
sorting techniques for use by the 
sort/merge program. The techniques are 
described in the sort/merge program 
publication. The selected technique must 
be specified in an optional argument (arg 
9) to the entry point used. The optional 



• A declaration of the variable RETURN 
CODE to receive the return code from the 
sort/merge program. 

• A CALL statement to invoke the entry 
point PLISRTA. 

• statements to test the return code. 

The example uses the iriniiruir of data 
sets; one for input, one for output, and 
three direct-access storage extents en a 
single disk storage drive. 
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//0PT14#7 JOB 

//STEP1 EXEC PLIXCLG, PARM.PLI=' SI ZE ( 130K ), OBJECT' 
//PLI.SYSIN DD * 
EX106: PROC OPTIONS (MAIN) ; 

DCL RETURN_CODE FIXED BIN (31,0); 

CALL PLISRTA (' SORT FIELDS=( 7, 74, CH , A) ' , 
* RECORD TYPE=F,LENGTH=(80) *, 
45000, 

RETURN_CODE) ; 
IF RETURN_CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED') (A); 
ELSE IF RETURN_CODE = THEN PUT SKIP EDIT ('SORT COMPLETE*) 

(A) ; 
ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE') (A); 
END EX106; 
/* 

//GO.SORTIN DD * 

003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD 

002886BOOKER R.R. ROTORUA, MILKEDGE LANE, TOBLEY 

003077ROOKER 6 SON, LITTLETON NURSERIES, SHOLTSPAR 

059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON 

073872HOME TAVERN, WESTLEIGH 

000931FOREST, IVER, BUCKS 

/* 

//GO.SORTOUT DD SYSOUT=A, DCB=(RECFM=F,BLKSIZE=80) 

//GO. SYSOUT DD SYSOUT=A 

//GO.SORTLIB DD DSN=SYSl. SORTLIB, DISP=SHR 

//GO. SORTWK01 DD UNIT=2314 ,SPACE= (TRK,20 , ,CONTIG) 

//GO.SORTWK02 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 

//GO. SORTWK03 DD UNIT=2314 ,SPACE= (TRK,20 , ,CONTIG) 

Figure 14-7. invoking sort/merge via entry point PLISRTA 



| USING USER EXIT El5 TO PASS RECORDS TO 
BE SORTED (PLISRTB) 



The example in Figure 14-8 illustrates the 
use of entry point PLISRTB to enable 
records to be supplied to the sort by a 
PL/ I procedure. 

Like that in the previous example, the 
main procedure invokes the sort/merge 
program and tests the return code when 
processing is complete. Note that records 
to be sorted can be supplied only by the 
procedure invoked by way of user exit E15 
(in this case, procedure E15X). 

Each time procedure E15X is invoked by 
the sort/merge program, E15X reads a record 
from the input stream and passes it to the 
sort after the appropriate return code has 
been passed. 



USING USER EXIT E35 TO HANDLE SORTED 
RECORDS (PLISRTC) 



The example in Figure 14-9 illustrates the 



use of entry point PLISRTC tc enable 
records to te supplied from the sort to the 
PL/I procedure E35X. As in previous 
examples, the main procedure invokes the 
sort/merge program and tests the return 
code when processing is complete. Each 
time procedure E35X is invoked by the 
sort/merge program, it receives a sorted 
record as a parameter, prints it, and 
requests the next record frcir the 
sort/merge program by passing it the 
appropriate return code. 



PASSING RECORDS TO BE SORTED, AND 
RECEIVING SORTED RECORDS (PLISRTD) 



The example in Figure 14-10 illustrates the 
use of entry point PLISRTD to enable 
records to be supplied to the sort from a 
PL/I procedure and sorted records tc be 
supplied from the sort to a PL/I procedure. 
As in previous examples, the main procedure 
invokes the sort/merge program and tests 
the return code when processing is 
complete. The use of the E15 user exit is 
identical to that in Figure 14-8; the use 
of the E35 user exit is identical to that 
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//OPTl4#8 JOB 

//STEP1 EXEC PLIXCLG # PARM.PLI= , SIZE(130K), OBJECT' 
//PLI.SYSIN BD * 
EX10 7: PROC OPTIONS (MAIN) ; 

DCL RETURN_CODE FIXED BIN(31,0); 

CALL PLISRTB (' SORT FIELDS= (7, 74,CH,A) ', 
' RECORD TYPE=F,LENGTH= (80) ', 
45000, 

RETURN_CODE f 
E15X) ; 
IF RETURN_CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED') (A); 
ELSE IF RETURN_CODE = THEN PUT SKIP EDIT ('SORT COMPLETE *) (A); 
ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE*) (A); 

E15X: /* THIS PROCEDURE OBTAINS RECORDS FROM THE INPUT STREAM */ 
PROC RETURNS (CHAR (80)) ; 

DCL SYSIN FILE RECORD INPUT, 

INFIELD CHAR (80) INIT ( ' '); 

ON ENDFILE (SYSIN) BEGIN; 

PUT SKIPO) EDIT ('END OF SORT PROGRAM INPUT') (A); 
CALL PLIRETC(8); /* SIGNAL END OF SORT INPUT */ 
GOTO ENDE15; 
END; 

READ FILE (SYSIN) INTO (INFIELD); 

CALL PLIRETC(12); /* INPUT TO SORT CONTINUES */ 
ENDE15: RETURN (INFIELD); 

END E15X; 
END EX107; 
/* 

//GO. SYSIN DD * 

003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD 
002886BOOKER R.R. ROTORUA, MILKEDGE LANE, TOBLEY 
003077ROOKER g SON, LITTLETON NURSERIES, SHOLTSPAR 
059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON 
07387 2HOME TAVERN, WESTLEIGH 
000931FOREST, IVER, BUCKS 
/* 

//GO. SORTOUT DD SYSOUT=A,DCB= (RECFM=F,BLKSIZE=80) 
//GO.SYSOUT DD SYSOUT=A 

//GO. SORTLIB DD DSN=SYSl .SORTLIB,DISP=SHR 
//GO.SORTWK01 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 
//GO. SORTWK02 DD UNIT=2314 ,SPACE= (TRK ,20 , ,CONTlG) 
//GO.SORTWK03 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 

Figure 14-8. Invoking sort/merge via entry point PLISRTB 



in Figure 14-9. 

The sequence of events is as follows: 

1. The PL/I program invokes the 
sort /merge program. 

2. The sort/merge program invokes the E15 
routine for each input record until 
the return code is set to 8 . 

3. The sort/merge program invokes the E35 
routine for each sorted record until 
all the sorted records have been 
passed or until the E35 routine 



requests no more records. 



SORTING VARIABLE -LENGTH RECORDS 



The following points should be considered 
when sorting variable-length records: 

• The portion of a variable-length record 
that contains the control field or 
fields on which the sort is to be 
performed must be present and of the 
same length for every reccrd to be 
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//0PT14#9 JOB 

//STEP1 EXEC PLIXCLG,PARM.PLI=' SIZE (130K) , OBJECT' 
//PLI.SYSIN DD * 
EX108: PROC OPTIONS (MAIN) ; 

DCL RETURN_CODE FIXED BIN (31,0); 

CALL PLISRTC (' SORT FIELDS= (7 , 74 ,CH, A) ', 
' RECORD TYPE=F,LENGTH=(80) ', 
45000, 

RETURN_CODE r 
E3 5X); 
IF RETURN_CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED 1 ) (A); 
ELSE IF RETURN_CODE = THEN PUT SKIP EDIT ('SORT COMPLETE' ) (A) ; 
ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE') (A); 

E35X: /* THIS PROCEDURE OBTAINS SORTED RECORDS */ 
PROC ( INREC) ; 

DCL INREC CHAR (80); 

PUT SKIP EDIT (INREC) (A); 

CALL PLIRETC(4); /* REQUEST NEXT RECORD FPOM SORT */ 

END E35X; 
END EX 10 8; 
/* 

//GO.SYSOUT DD SYSOUT=A 

//GO. SORTLIB DD DSN=SYSl .SORTLIB, DISP=SHR 
//GO.SORTWK01 DD UNIT=2314 f SPACE=(TRK, 20, ,CONTIG) 
//GO. SORTWK02 DD UNIT=2314 ,SPACE= (TRK ,20 , ,CONTIG) 
//GO.SORTWK03 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 
//GO. SORTIN DD * 

003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD 
002996BOOKER S.W. ROTORUA, MILKEDGE LANE, TOBLEY 
003077ROOKER 6 SON, LITTLETON NURSERIES, SHOLTSPAR 
059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON 
07387 2HOME TAVERN, WESTLEIGH 
000931FOREST, IVER, BUCKS 
/* 

Figure 14-9. Invoking sort/merge via entry point PLISRTC 
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//OPTl4#10 JOB 

//STEPl EXEC PLIXCLG,PARM.PLI='SIZE(130K) , OBJECT' 
//PLI.SYSIN DD * 
EX109: PROC OPTIONS (MAIN) ; 

DCL RETURN_CODE FIXED BIN(31,0); 

CALL PLISRTD (' SORT FIELDS=(7, 74,CH,A) ', 
' RECORD TYPE=F,LENGTH= (8 0) ', 
45000, 

RETURN_CODE, 
E15X, 
E35X); 
IF RETURN_CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED') (A); 
ELSE IF RETURN_CODE = THEN PUT SKIP EDIT ('SORT COMPLETE' ) (A) ; 
ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE ' ) (A) ; 

E15X: /* THIS PROCEDURE OBTAINS RECORDS FROM THE INPUT STREAM */ 

PROC RETURNS (CHAR( 80)); 

DCL INFIELD CHAR (80) INIT( ' '); 

ON ENDFILE(SYSIN) BEGIN; 

PUT SKIP(3) EDIT ('END OF SORT PROGRAM INPUT. ', 

•SORTED OUTPUT SHOULD FOLLOW) (A); 
CALL PLIRETC(8); /* SIGNAL END OF SORT INPUT */ 
GOTO ENDE15; 
END; 

GET FILE (SYSIN) EDIT (INFIELD) (A(80)); 
PUT SKIP EDIT (INFIELD) (A); 

CALL PLIRETC(12); /* INPUT TO SORT CONTINUES */ 
ENDE15: RETURN (INFIELD); 

END E15X; 

E35X: /* THIS PROCEDURE OBTAINS SORTED RECORDS */ 

PROC (INREC) ; 

DCL INREC CHAR (80); 

PUT SKIP EDIT (INREC) (A) ; 
NEXT: CALL PLIRETC(4); /* REQUEST NEXT RECORD FROM SORT */ 

END E35X; 
END EX109; 
/* 

//GO.SYSOUT DD SYSOUT=A 

//GO. SORTLIB DD DSN=SYSl .SORT LIB, DISP=SHR 
//GO.SORTWK01 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 
//GO. SORTWK02 DD UNIT=2314 ,SPACE= (TRK,20 , ,CONTlG) 
//GO.SORTWK03 DD UNIT=2314, SPACE=(TRK, 20, ,CONTIG) 
//GO. SYSIN DD * 

003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD 
002996BOOKER S.W. ROTORUA, MILKEDGE LANE, TOBLEY 
003077ROOKER 6 SON, LITTLETON NURSERIES, SHOLTSPAR 
059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON 
07387 2HOME TAVERN, WESTLEIGH 
000931FOREST, IVER, BUCKS 
/* 

Figure 14-10. Invoking sort/merge via entry point PLISRTD 
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//0PT14#11 JOB 

//STEP1 EXEC PLIXCLG,PARM.PLI='SIZE(130K) , OBJECT' 

//PLI.SYSIN DD * 

/* PL/I EXAMPLE USING PLISRTB TO SORT VARIABLE-LENGTH RECORDS */ 
EX1306: PROC OPTIONS (MAIN) ; 

DCL RETURN_CODE FIXED BIN (31,0); 

CALL PLISRTB (' SORT FIELDS=( 11, 14,CH,A) ,WORK=4 ', 
• RECORD TYPE=V,LENGTH=(84,,,24,44) ' , 
45000 

RETURN_CODE, 
E15X) ; 
IF RETURN_CODE = THEN PUT SKIP EDIT ('SORT COMPLETE' ) (A) ; 
ELSE IF RETURN_CODE=16 THEN PUT SKIP EDIT ('SORT FAILED' ) (A) ; 
ELSE PUT SKIP EDIT ('INVALID RETURN CODE' ) (A) ; 
E15X: PROC RETURNS (CHAR (8 0) VARYING); 
DCL STRING CHAR (80) VAR; 
ON ENDFILE(SYSIN) BEGIN; 

PUT SKIP EDIT ('END OF INPUT') (A); 
CALL PLIRETC(8); 
GOTO ENDE15; 
END; 
GET EDIT (STRING) (A(80)); 

1= INDEX (STRING | | * ',' ')-l; /* RESET THE LENGTH CF THE */ 
STRING = SUBSTR(STRING,1,I); /* STRING FROM 80 TO LENGTH */ 

/* OF THE TEXT IN EACH INPUT*/ 
/* RECORD */ 

PUT SKIP EDIT( I, STRING) (F( 2) ,X(3) ,A) ; 
CALL PLIRETC(12) ; 
RETURN (STRING); 
END15: END E15X; 

END EX1036; 
/* 

//GO. SYS IN DD * 

003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD 
002886BOOKER R.R. ROTORUA, MILKEDGE LANE, TOBLEY 
003077ROOKER 6 SON, LITTLETON NURSERIES, SHOLTSPAR 
059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON 
073872HOME TAVERN, WESTLEIGH 
000931FOREST, IVER, BUCKS 
/* 

//GO.SORTOUT DD SYSOUT=A, DCB=(RECFM=V,BLKSIZE=88) 
//GO. SYSOUT DD SYSOUT=A 

//GO.SORTLIB DD DSN=SYSl. SORTLIB, DISP=SHR 
//GO. SORTWK01 DD UNIT=2314 ,SPACE= (TRK,20 , ,CONTIG) 
//GO.SORTWK02 DD UNIT=2314, SPACE= (TRK, 20, ,CONTIG) 
//GO. SORTWK03 DD UNIT=2314 ,SPACE= (TRK ,20 , ,CONTlG) 

Figure 14-11. sorting variable-length records 



sorted. A sort cannot be performed on 
control fields whose length or position 
within the record is liable to alter. 
Thus the control fields would be 
expected within the minimum length given 
for the records in the record statement. 

The length of each record is recorded in 
the first four bytes of the record. 
Provision for this length field should 
be made when you specify the sort 
control fields in the SORT control 
statement . 

Varying- length strings passed from an 
E15 procedure will have the PL/I length 



field converted into a length-field for 
variable-length records. The length 
will be the current length of the 
character string plus four bytes for the 
length field. A fixed-length string 
will have the length field added to form 
a variable-length reccrd. Consequently, 
fixed-length strings of different 
lengths can be returned f rcir the same 
procedure. 

An E35 procedure can only use adjustable 
strings to receive variable-length 
records from the sort program. 

The example in Figure 14-11 shows a 
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program to read fixed-length (80-fcyte) 
records from SYS IN, convert them to 
varying-length strings, sort them, and 
print them. The maximum length of each 
variable-length record after conversion 
from a string is 84 bytes including the 
four-byte control field. The maximum block 
size for these records in the SORTOUT data 
set is 88 bytes. The sort field starts on 
byte 7 of the string. Consequently, it is 
defined as starting on byte 11 of the 
record to allow for the four- byte control 
field. 
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Chapter 15: Checkpoint/ Rest art 



The PL/ 1 Checkpoint/Restart feature 
provides a convenient method of taking 
checkpoints during the execution of a long- 
running program in a batch environment. It 
cannot be used in a TSO environment. 

At points specified in the program, 
information about the current status of the 
program is written as a record on a data 
set. If the program terminates due to a 
system failure, this information can be 
used to restart the program close to the 
point where the failure occurred, avoiding 
the need to rerun the program completely. 

This restart can be either automatic or 
deferred. An automatic restart is one that 
takes place immediately (provided the 
operator authorizes it when requested by a 
system message) . A deferred restart is one 
that is performed later as a new job. 

You can request an automatic restart 
from within your program without a system 
failure having occurred. 

PL/I Checkpoint/Restart uses the 
Advanced Checkpoint/Restart Facility of the 
operating system. This is fully described 
in the publication Advanced 
Checkpo in t /Re s tar t . 

To use checkpoint/restart you must do 
the following: 

• Request, at suitable points in your 
program, that a checkpoint record is 
written. This is done with the built-in 
subroutine PLICKPT. 



• Provide a data set on which the 
checkpoint record can- be written. 

• Also, to ensure the desired restart 
activity, you may need to specify the RD 
parameter in the EXEC or JOB statement 

(see the publication JCL Reference ) . 

Note ; You should be aware of the 
restrictions affecting data sets used by 
your program. These are detailed in the 
publication Advanced Checkpoint/Restart . 



Writing a Checkpoint Record 



Each time you want a checkpoint record to 
be written, you must invoke, from your PL/I 
program, the built-in subroutine PLICKPT. 



The CALL statement has the fcrir: 

CALL PLICKPT [ (ddname t , check - 
id [ , org [ , code] ]]])]; 

| The four arguments are all optional. If 
jan argument is not used, it need not be 
| specified unless another argument that 
j follows it in the given order is specified. 
| In this case, the unused argument must be 
j specified as a null string. The following 
j paragraphs describe the arguments. 

"ddname" is a character string constant or 
variable specifying the name of the DD 
statement defining the data set that is to 
be used for checkpoint records. If this 
argument is omitted, the system will use 
the default ddname SYSCHK. 

"check- id" is a character string constant 
or variable specifying the name that you 
want to assign to the checkpoint record so 
that you can identify it later, if 
required. If this argument is omitted, the 
system will supply a unique identification 
and print it at the operator's console. 

"org" is a character string constant or 
variable with the attributes CHARACTER (2) 
whose value indicates, in operating system 
terms, the organization of the checkpoint 
data set. PS indicates sequential (that 
is, CONSECUTIVE) organization; PO 
represents partitioned organization. If 
this argument is omitted, PS is assumed. 

"code" is a variable with the attributes 
FIXED BINARY (31), which can receive a 
return code from PLICKPT. The return code 
has the following values: 

A checkpoint has been successfully 
taken. 

4 A restart has been successfully made. 

8 A checkpoint has not been taken. The 
PLICKPT statement should be checked. 

12 A checkpoint has not been taken. 

Check for a missing DD statement, a 
hardware error, or insufficient space 
in the data set. A checkpoint will 
fail if taken while a DISPLAY 
statement with the REPLY option is 
still incomplete or if the program is 
using multitasking. 

16 A checkpoint has been taken, but ENQ 
macro calls are outstanding and will 
not be restored on restart. This 
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situation will not normally arise for 
a PL/T program. 



AUTOMATIC RESTART AFTER A SYSTEM 
FAILURE 



Checkpoint Data Set 



A DD statement defining the data set on 
which the checkpoint records are to be 
placed, must be included in the job control 
procedure. This data set can have either 
CONSECUTIVE or partitioned organization. 
Any valid ddname can be used. If you use 
the ddname SYSCHK, you do not need to 
specify the ddname when invoking PLICKPT. 

A data set name need be specified only 
if you want to keep the data set for a 
deferred restart. The I/O device can be any 
magnetic-tape or direct- access device. 

If you want to obtain only the last 
checkpoint record, then specify status as 
NEW (or OLD if the data set already 
exists) . This will cause each checkpoint 
record to overwrite the previous one. 

If you want to retain more than one 
checkpoint record, specify status as MOD. 
This will cause each checkpoint record to 
be added after the previous one. 

If the checkpoint data set is a library, 
then "check-id" is used as the member-name. 
Thus a checkpoint will delete any 
previously -taken checkpoint with the same 
name. 

For direct access storage, enough 
primary space should be allocated to store 
as many checkpoint records as you will 
retain. You can specify an incremental 
space allocation, but it will not be used. 
A checkpoint record is approximately 5000 
bytes longer than the area of main storage 
allocated to the step. 

No DCB information is required, but you 
can include any of the following, where 
applicable: 

OPTCD=W, OPTCD=C, RECFM=UT , NCP=2 , TRTCH=C 

These subparameters are described in 
Appendix A. 



Performing a Restart 



A restart can be automatic or deferred. 
Automatic restarts can be made after a 
system failure or from within the program 
itself. All automatic restarts need to be 
authorized by the operator when requested 
by the system. 



If a system failure occurs after a 
checkpoint has been taken, the automatic 
restart will occur at the last checkpoint 
if you have specified RD=R (or omitted the 
RD parameter) in the EXEC or JOB statement. 

If a system failure occurs before any 
checkpoint has been taken, then an 
automatic restart, from the beginning of 
the job step, can still occur if you have 
specified RD=R in the EXEC or JOB 
statement. 

If a system failure occurs after a 
checkpoint has been taken, then you can 
still force automatic restart from the 
beginning of the job step by specifying 
RD=RNC in the EXEC or JOB statement. 



AUTOMATIC RESTART FROM WITHIN THE 
PROGRAM 



An automatic restart can be requested at 
any point in your program. The rules 
applying to the restart are the s aire as for 
a restart after a system failure. To 
request the restart, you must execute the 
statement: 

CALL PUREST; 

To effect the restart, the compiler 
terminates the program abnormally, with a 
system completion code of 4092. Therefore, 
to use this facility, the system ccirpleticn 
code 4092 must not have been deleted from 
the table of eligible codes at systeir 
generation. 



DEFERRED RESTART 



To ensure that automatic restart activity 
is canceled, but that the checkpoints are 
still available for a deferred restart, 
specify RD=NR in the EXEC or JOB statement 
when the program is first executed. 

If a deferred restart is subsequently 
required, the program must be submitted as 
a new job, with the RESTART parameter in 
the JOB statement. The RESTART parameter 
specifies the job step at which the restart 
is to be made and, if you want to restart 
at a checkpoint, the name of the checkpoint 
record. The RESTART parameter has the form: 

RESTART=(stepname[, check-id] ) 
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For a restart from a checkpoint, you 
must also provide, immediately before the 
EXEC statement for the job step, a DD 
statement, with the name SYSCHK, defining 
the data set containing the checkpoint 
record. 



CALL PLICANC; 



However, if you have specified RD=R cr 
RD=RNC in the JOB or EXEC statement, 
automatic restart can still take place froir 
the beginning of the job step. 



MODIFYING CHECKPOINT/RESTART ACTIVITY 



Also, any checkpoints already taken will 
still be available for a deferred restart. 



You can cancel automatic restart activity 
from any checkpoints taken in your program 
by executing the statement: 



You can cancel any automatic restart, 
and also the taking of checkpoints, even if 
requested in your program, by specifying 
RD=NC in the JOB or EXEC statement. 
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Appendix A: DCB Subparameters 



This appendix shows you how to code data 
set information in the DCB parameter of the 
DD statement and how to make use of 
existing DCB information. It also contains 
an alphabetic list of the subparameters 
that apply to a PL/I program. These 
subparameters are specified in the DCB 
parameter of the DD statement. Chapter 3 
shows you how to write a DD statement and 
chapter 6 shows you how to use the name 
(ddname) of the DD statement. For a full 
description of the DD statement see the job 
control language publications. 



INFORMATION IN SIMILAR DATA SETS 



You can copy DCB information from the label 
of a similar data set by coding: 

DCB=dsname 

where "dsname" is the naire cf the data set 
containing the information you want to 
copy. This data set must be cataloged, it 
must be on a direct- access storage device, 
and the volume containing it roust be 
mounted before execution of the job step. 



DCB Parameter 



INFORMATION IN AN EARLIER DATA SET 



The DCB parameter enables you to add 
information about your data set to the data 
control block (DCB) generated when the 
associated file in your PL/I program is 
opened. The information to be added is 
defined in one or more subparameters . 
These subparameters correspond to the 
operands of the DCB macro instruction and 
are specified in the same way. For a full 
description of macro instructions see the 
supervisor and data management macro 
instructions publication. 

Code the DCB parameter as follows: 

DCB=subparameter 

or 

DCB= (subparameter, subparameter) 
For example: 

DCB=BLKSIZE=80 

DCB= (RECFM=FB , LRECL=8 ) 



Using Existing DCB Information 



You can use the DCB parameter to make use 
of DCB information that already exists 
either in the label of a similar data set, 
or that has been specified in, the DCB 
parameter of an earlier DD statement. 



You can also copy the DCB information froic 
an earlier DD statement in a job by coding: 

DCB=*. stepname. ddname 

where the asterisk tells the operating 
system that this is to be a backward 
reference, "stepname" is the name of the 
job step in which the earlier ED statement 
appears, and "ddname" is the name of the 
earlier DD statement. If the earlier DD 
statement is in a cataloged procedure you 
must include the procedure step name as 
well as the job step name, for example by 
coding: 

DCB=* . stepname. procstepnaroe. ddname 



Overriding Existing DCB Information 

If the existing DCB information does not 
meet your requirements exactly you can 
override any of the subparanneters by 
specifying the required information in a 
new subparameter. For example, if an 
existing DD statement named IN in a job 
step named COMP has the following DCE 
parameter: 

DCB= (RECFM=FB,LRECL=80) 

and you want LRECL to be 100, simply code: 

DCB=(*.COMP.IN,LRECL=100) 
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Sub parameters of the DCB 
Parameter 

The following is a summary of those 
subparameters that can apply to your PL/I 
program. The notation used in the 
descriptions is as follows: 

n unsigned decimal integer 

| indicates a choice 

{} braces indicate that you must select 
one line from the items enclosed 

[] brackets indicate that the item 
enclosed is optional. 

Code capital letters and numbers exactly as 
shown. 



EBCDIC. ) 

A ASCII (8-track) 

B Burroughs (7- track) 

C NCR (8-track) 

F Friden (8-track) 

I IBM BCD perforated -tape transmission 
code (8-track) 

N No conversion required (F- format 
records only) 

T Teletype (5-track) 

If no code is specified, I is assuired. 



BLKSIZE=n 



specifies the length in bytes of a block. 
The maximum length is 32760 bytes. 

For fixed- length records, the block size 
must be an integral multiple of the record 
length (LRECL) ; the minimum size is 1 byte. 

For variable- length (V-format and VB- 
format) records, the block size must be at 
least eight bytes larger than the largest 
item of data that you expect to read or 
write (that is, four bytes larger than the 
record length specified in LRECL) . 
However, if the records are spanned (VS- 
format and VBS-format), you can specify 
block size independently of record length. 
The minimum block size for data sets on 
magnetic tape is 18 bytes. 



BUFNO=n 



specifies the number of buffers to be used 
in accessing the data set. The maximum 
number is 255 (unless another maximum has 
been determined for your installation 
during system generation). For a STREAM 
file or BUFFERED RECORD file, if you do not 
specify the number of buffers or you 
specify zero buffers, the number is assumed 
to be two. 



C0DE=A1B|C|F|I|N|T 



specifies the code in which paper tape is 
punched. (Data is read into main storage 
and then converted from that code to 



CYLOFL=n 



specifies, for an INDEXED data set, the 
number of tracks of each cylinder tc be 
reserved for the records that overflow from 
other tracks in that cylinder. The 
theoretical maximum is 99, but the 
practical limit varies with the particular 
device. 

There must be at least one track in each 
cylinder to hold the prime data. 



DEN=0 1 1 1 2 I 3 

specifies the recording density for 
magnetic tape as follows: 

Bytes per inch (bpi) 

DEN 7-track 9-track 






200 


- 


1 


556 


.- 


2 


800 


800 


3 


_ 


1600 



The density assumed if you omit this 
subparameter is: 

7-track: 200 bpi 

9-track (single density); 800 bpi 

9-track (dual density): 1600 bpi 

(The subparameter TRTCH is required for 7- 
track tape. ) 
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DSORG=IS I DA 

specifies the organization of the data set 
you are creating: 

IS (indexed sequential): INDEXED data set 

DA (direct access): REGIONAL data set 

This subparameter is not required for 
CONSECUTIVE data sets. 



FONC= function 



specifies the function or functions to be 
performed by an IBM 3525. The following 
values of "function" are valid: 



I 


WT 


RWX 


PWXT 


R 


WXT 


RWT 


RPW 


P 


RP 


RWXT 


RPWX 


W 


RPD 


PW 


RPWXT 


WX 


RW 


PWX 


RPWD 



The letters have the following meanings: 

I - Interpret 

R - Read 

P - Punch 

W - Print 

D - Data protection 

X - Printer 

T - Two- line printer 



on which the record is situated and 
continues to the end of the track 
containing the last record to be searched 

For REGIONAL (3), LIMCT specifies the 
number of tracks to be searched. 



LRECL=n 



specifies the length of a record in bytes; 
the maximum length is 32760 bytes for F- 
format records, and 32756 bytes for V- 
format records. You must specify a record 
length for blocked records. 

For F- format and FB- format records, the 
record length must not exceed the blcck 
size (B1KSIZE) value; the minimum length is 
1 byte. 

For V-format records, give the maximum 
record length including the four control 
bytes required by the operating system; the 
minimum record length for V-fcrirat records 
is 14 bytes (ten bytes of data and four 
control bytes) . The record length f cr V- 
format and VB- format records must be at 
least four bytes less than the block size 
(BLKSIZE) value; however, for VS-format and 
VBS-format records, it can be specified 
independently of block size. 



MODE=tE|CHO|R] 



KEYLEN=n 



specifies the length in bytes of the 
recorded key of records in INDEXED, 
REGIONAL(2), and REGIONAL (3) data sets 
The maximum key length is 255 bytes. 



specifies the mode of operation for a card 
reader cr punch. E indicates EBCDIC, and C 
indicates column binary. O specifies 
Optical Mark Read mode on an IBM 3505, and 
R specifies Read Column Eliminate mode on 
an IBM 3505 or 3525. 



LIMCT=n 



NCP=n 



limits the extent of the search for a 
record or space to add a record in a 
REGIONAL(2) or REGIONAL (3) data set beyond 
the region number specified in the source 
key. 

If you do not specify a limit, the 
search starts at the specified region and 
continues through the whole of the data 
set. 

For REGIONAL(2), LIMCT specifies the 
number of records to be searched. The 
search starts at the beginning of the track 



specifies the number of channel programs 
allocated to a file when it is opened: the 
number of simultaneous input/cutput 
operations on the file (that is, the number 
of incomplete event variables) cannct 
exceed the number of channel programs. The 
NCP subparameter applies only to direct 
access to INDEXED data sets, or sequential 
access to CONSECUTIVE or REGIONAL data sets 
that are unbuffered. The maximum number of 
channel programs is 99 (unless another 
maximum was established for your 
installation at system generation) ; the 
default value assumed if you omit the 
subparameter is 1. 
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For DIRECT access to an INDEXED data 
set, simultaneous input/output operations 
in excess of the number of channel programs 
are queued until a channel program becomes 
available . 

For UNBUFFERED SEQUENTIAL access to 
CONSECUTIVE or REGIONAL data sets, the 
ERROR condition is raised if there are too 
many concurrent operations. 

The NCP subparameter overrides the BUFNO 
subparameter or the BUFFERS option of the 
ENVIRONMENT attribute. One buffer is 
allocated for each channel program. 



NTM=n 



specifies, for an INDEXED data set, the 
number of tracks in the cylinder index 
referred to by each master index entry, and 
the number of tracks within each level of 
the master index referred to by each entry 
in the next higher level. The maximum 
value for n is 99. (See also OPTCD=M later 
in this chapter.) 



OPTCD=option list 



lists optional data management services. 
To indicate the services you require, code 
the appropriate letters (see below) without 
separating blanks, in place of "option 
list" (for example, OPTCD=LY) . 

OPTCD=C requests chained scheduling, 
which improves input/output performance by 
reducing the time required to transmit 
blocks to and from auxiliary storage 
devices. In chained scheduling, the data 
management routines bypass the normal 
input/output scheduling routines and chain 
several input/output operations together; a 
series of read operations, for example, is 
issued as a single chain of commands 
instead of several separate commands. 

Chained scheduling is most useful in 
programs whose performance is input/output 
limited. If you use this feature, you 
should request at least three buffers or at 
least three channel programs. Chained 
scheduling can be used with CONSECUTIVE or 
REGIONAL SEQUENTIAL data sets; it should 
not be used for INPUT or UPDATE with U- 
format records. 

OPTCD=I requests an independent overflow 
area for an INDEXED data set; you must 
define this overflow area in a separate DD 
statement . 



OPTCD=L requests that a record in an 
INDEXED data set be recognized as deleted 
if its first byte contains (8)*1*E. 

OPTCE=M requests the creation of a 
master index in accordance with the 
information given in the NTM subparameter. 

OPTCD=U suppresses the raising of the 
TRANSMIT condition when an invalid 
character is passed to a printer with the 
universal character set feature. A blank is 
printed in place of the invalid character. 

OPTCD=W requests a write validity check 
for a direct-access device. 

OPTCD=Y requests that the data 
management routines use the cylinder 
overflow area for overflow records in an 
INDEXED data set. The size of the overflow 
area is established by CYLOFL=n. 



RECFM= 



RECFM= 



( F[B] [S] ) 
< VtB] [S3 > 



[Bi [s: 

[B] [S3 > [T] [A|M3 



indicates the record format as follows: 

F Fixed-length records 

V Variable- length records 

U Undefined-length records 

If you do not specify a record format, 
U-format is assumed, except for PRINT 
files, for which V- format is the default 
assumption. 

The optional subfields are: 

B Blocked records. 

S Standard (fixed-length records only) . 
No blocks, except possibly the last, 
will be shorter than the specified 
block size. 

S Spanned (variable-length records 

only) . If variable -length records are 
spanned, the record length specified 
by LRECL can exceed the block size 
specified by BLKSIZE; if necessary,, 
the records are segmented and the 
segments are placed in consecutive 
blocks. If the records are unblocked, 
each block contains only one record or 
segment; if the records are blocked, 
each block contains as many records or 
segments as it can accommodate. 

T Track overflow. Track overflow is an 
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No 
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No | 



Figure A-l. Specifying tape recording 
techniques using the TRTCH 
subparameter 



operating system feature that can be 
in corpora tedduring system generation. 
It allows a block to overflow from one 
track of a direct-access device to 
another. Track overflow is useful in 
achieving greater data -packing 
efficiency, and also allows the size 
of a record to exceed the capacity of 
a track. 

Note ; You cannot use track overflow for 
REGI0NAL(3) data sets with U-format or V- 
format records or for INDEXED data sets. 

A The first byte of each record contains 
an ANS printer/ punch control code. 

M The first byte of each record contains 
an IBM System/360 printer/punch 
control code. 



RKP=n 



specifies for an INDEXED data set, the 
position (n) of the first byte of an 
embedded key relative to the beginning of 
the record (byte 0). RKP=0 implies that 
the key is not embedded. (For example, if 
"XYZ" is the key embedded in the record 
"ABCXYZDEF", RKP=3. ) 



STACK=U2 



refers to a card reader or punch; 



1 All cards read or punched are to be 
fed into stacker 1 . 

2 All cards read or punched are tc be 
fed into stacker 2. 

Stacker 1 is assumed if you omit this 
subparameter. If you want stacker 3„ 
specify the ANS machine- code character in 
the RECFM parameter of the DD statement,, 
and insert the appropriate character as the 
first data byte. 



TRTCB=C1T | E|ET 



is required when a data set is recorded or 
is to be recorded on 7-track tape. It 
specifies the recording technique to be 
used as shown in Figure A-l. 



Notes 

Data conversion and translation : data on 
9-track magnetic tape, like that in irain 
storage, is held in 8-bit bytes, a ninth 
bit being used for parity checking; data en 
7-track tape is held in the form of 6-bit 
characters with a parity bit. The 
conversion feature of the 24 CO series 
magnetic-tape drives treats all data as if 
it were in the form of a bit string, 
breaking the string into grcups of six bits 
for writing on 7-track tape, or into groups 
of eight bits for reading into main 
storage. The translation feature changes 
the form in which character data is held 
from 8-bit EBCDIC to 6 -bit ECD or vice 
versa. If you specify neither conversion 
nor translation, only the last six tits of 
each 8-bit byte are transmitted; the first 
two are lost on output and are set tc zero 
on input. 

Parity ; Odd parity checking is normally 
used in IBM System/ 3 60, but you should 
specify even parity if you want to read a 
tape that was written by a system using 
even parity, or to write a tape for a 
system that demands even parity. 

Choice of technique ; The use of a 
technique other than C restricts the 
character set in which data can be written 
if it is subsequently to be reread and 
result in the same bit configuration in 
main storage. (An 8-bit code offers 256 
possible configurations, but a 6-bit code 
only 64.) For stream-oriented or record- 
oriented transmission of character strings 
or pictured data, you can use technique C 
or T; you can also specify ET if your 
program is written in the 48 -character set. 
(Seven-track tape recording systems 
indicate a zero bit by the absence cf 
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magnetization of the tape. Even parity 
checking does not allow the code 000000 to 
be used to represent the character zero, 
since an unmagnetized band is not 
acceptable on the tape. Therefore the code 
that would otherwise represent a colon (:) 
is used for the character zero, precluding 
the use of the full PL/I 60-character set.) 
For record-oriented transmission of 
arithmetic data, you must specify technique 
C. 



Block Size : A PL/ 1 program cannot be used 
to access a data set on a 7-track tape 
recorded with a block size that is net a 
multiple of four bits. For example, a 7- 
track tape with a block size of 175 has 
6*175 bits, that is, 1,050 bits in each 
block and cannot be read unless it is first 
modified by the the IEBCOPY utility 
program. 



198 OS PL/I Optimizing Compiler: Programmer's Guide 



Appendix B: Compatibility with the PL/I(F) Compiler 



Some features of the PL/I Optimizing 
Compiler implementation are incompatible 
with the PL/I (F) Compiler implementation. 
The most significant incompatibilities are 
listed below. In every case, the 
description given is of the optimizing 
compiler implementation. Programs which 
were written for the (F) compiler and which 
use any of these features should be 
reviewed before compiling them with the 
optimizing compiler to ensure that they 
will return the same results. 

A number of the differences given here 
are also given in the general information 
manual for this compiler. The general 
information manual also contains some of 
the implementation limitations and 
restrictions of this compiler. The 
language reference manual for this compiler 
gives full details of the implementation of 
each language feature. 



Areas 



not lie within bytes that contain data 
belonging to other variables. 

The ALLOCATION built-in function returns 
a fixed-binary value giving the number 
of generations of the argument that 
exist in the current task. 

The NULLO built-in function is net 
implemented in the optimizing compiler. 
The NULL built-in function can be used 
for offset variables as well as for 
pointer variables. 

The CNCOUNT built-in function can be 
used in any on- unit and gives the number 
of interrupts remaining tc be processed 
at any stage in the execution of the 
current task, in particular, this 
includes event and non-event I/O and 
multiple computational interrupts. In 
the case of event I/O, the value of 
ON COUNT is the number of remaining 
exceptional conditions to be processed 
as a result of the execution of the WAIT 
statement. 



The (F) compiler holds the length of an 
area in the first 16 bytes of the area. 
The optimizing compiler holds the length of 
an area in a descriptor outside the area. 



Arrays and Structures 



When using REGIONAL (1) organization, the 
value returned by the ONKEY built-in 
function for a specification error 
consists of the last eight bytes of the 
source key, padded on the right with 
blanks if necessary. This value is 
returned for all I/O conditions ether 
than ENDFILE, or other than ERROR raised 
as standard system action for an I/O 
condition. 



• The maximum number of dimensions in an 
array is 15. 

• The maximum depth of a structure is 15, 



Built-in Functions 



Built-in functions are recognized on the 
basis of context only, so that all 
programmer -defined external procedures 
must be declared explicitly. Built-in 
functions and pseudovariables without 
arguments, such as TIME and ONCHAR, must 
also be declared explicitly with the 
BUILT IN attribute, or contextually with 
a null argument list, for example: 
TIME( ). 

For a variable to be a valid argument to 
the ADDR built-in function it must be 
connected and its left extremity must 



In a RECORD I/O statement with the KEY 
or KEYFROM option, the ONKEY built-in 
function returns a null string when the 
ERROR condition is raised. 

In a RECORD I/O statement referring to a 
KEYED file (but with no KEY, KEYFROM, or 
KEYTC option specified) the ONKEY built- 
in function returns the recorded key. 

The PROD built-in function accepts 
arguments that are arrays of either 
fixed-point or floating-point elements. 
The value returned has the same scale as 
the argument given, except for 
fractional fixed-point arguments for 
which the result is in floating-point. 

If the first argument of the ROUND 
built-in function is a string, it is 
converted to arithmetic and rounded; the 
first argument must be convertible to 
arithmetic. Also, a different formula is 
used to determine the precision cf a 
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fixed- point result. 

The SUBSTR built-in function returns a 
non- varying string. 

The SUM built-in function accepts 
arguments that are arrays of either 
fixed- point or floating-point elements . 
The value returned has the same scale as 
the argument given. 

The arguments of the TRANSLATE built-in 
function are converted to character- 
strings in all cases. 

The first 16 bits of the result returned 
by the UNSPEC built-in function for a 
varying string argument represent the 
current length of the string. 



Checkpoint/Restart 



The arguments to the function PLICKPT are 
mandatory . 



defining - B(l) will refer to the first 
three characters of Ad), B(2) to the 
first three characters of A (2), and so 

on. 

If string overlay defining is required, 
the user must specify POSITION (1) on 
the declaration of the defined item (B 
in the example above). 

If the string lengths or bounds cf the 
defined item cannot be contained in the 
base, simple defining will be assumed. 

For example: 

DECLARE A (6) CHAR (6) , 

B (7) CHAR (3) DEFINED (A); 

In this example, simple defining will be 
used because the bounds of array B 
exceed the bounds of array A. 

If the DEFINED attribute is used with an 
array of pictures, the defined item must 
match the base item exactly. 



Conditions 



When used with arrays, the CHECK 
condition is raised after assignment to 
each element. The standard system 
action when an assignment is made to a 
single element of an array is to print 
the value of only the element assigned. 

The STRINGRANGE condition is not raised 
for SUBSTR (string, i, 0) when "i" is one 
greater than the length of "string". A 
null string is returned. 



Dependent Declarations 



Only one level of dependent declaration is 
allowed. 



DISPLAY Statement 



The maximum length of the reply is 72 
characters. 



Control Variable in DO statement 



The pseudo variables COMPLETION, COMPLEX, 
PRIORITY, and STRING are not allowed as the 
control variable of a DO statement. 



DEFINED Attribute 



Simple defining of strings and areas on 
a larger base is allowed. 

For example: 

DECLARE A (6) CHAR (6), 

B (3) CHAR (3) DEFINED A; 

This example will result in simple 



Dumps from PL/I Programs 



The object-time dump facility of the (F) 
compiler, IHEDUMP, requires a DD statement 
with the ddname PL1DUMP. Its equivalent in 
the optimizing compiler, PLIDUMP, requires 
a DD statement with the ddnane PLIDUMP. 
The optimizing compiler will attempt to use 
PLIDUMP if PLIDUMP is not available. 



I ENDPAGE Condition 



jwhen ENDPAGE is signaled it cannot be 
| raised again on the same page, except by 
| the use of a further SIGNAL statement. 
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Old form 

F(b) 

F(b,r) 

U(b) 

V(b) 

V(b,r) 

VBS(b,r) 

VS(b,r) 

Figure B-l. 



Converted to 

F BLKSlZE(b) RECSIZE(b) 
FB BLKSIZE(b) RECSIZE(r) 
U BLKSIZE(b) RECSIZE(b) 
V BLKSIZE(b) RECSIZE(b-U) 
VB BLKSIZE(b) RECSIZE(r) 
VBS BLKSIZE(b) RECSIZE(r) 
VS BLKSIZE(b) RECSIZE(r) 

Environment options 
recognized by the compiler 



Entry Names, Parameters, and Returned 
Values 



Each alternative entry expression in a 
GENERIC attribute is followed by a WHEN 
clause. The appearance of an entry name 
alternative does not constitute a 
declaration of the entry name. The 
alternative selected is the first for 
which each descriptor is a subset of the 
attributes of the corresponding argument 
in the generic reference. 

The dimension attribute is not allowed 
in a generic descriptor. 

In general, an entry name in parentheses 
causes a dummy variable to be created; 
for the function to be invoked, a null 
argument list is required. However, an 
entry name argument in parentheses, or 
an entry name without arguments, will be 
invoked if passed to a procedure whose 
parameter descriptor for the 
corresponding argument specifies an 
attribute other than ENTRY. 

External entry names must always be 
explicitly declared. 

Area and string extents in the RETURNS 
attribute or option must be represented 
by a decimal integer constant. 

The maximum depth of nesting in a 
descriptor list in the ENTRY attribute 
is 2. 

An aggregate expression involving 
strings may not be passed as an argument 
unless there is a corresponding 
parameter descriptor in which all string 
lengths are specified as decimal integer 
constants. 

An internal entry constant cannot be 
declared in a DECLARE statement. 
REDUCIBLE and IRREDUCIBLE may be 
specified on PROCEDURE and ENTRY 
statements. A scalar cannot be passed to 
an array parameter of an internal entry 



constant if the parameter^ bounds are 
specified by asterisks. 



ENVIRONMENT Attribute 



The optimizing compiler will recognize 
and convert the previous ly-impleirented 
forms of the options shown in Figure B- 
1, and will issue a message stating that 
they are obsolete. 

There are two new data set 
organizations, TP (M) and TP(R), 
associated with teleprocessing. TP(M) 
implies the transmission cf whcle 
messages; TP(R) implies the transmission 
of records. Both are valid only for 
TRANSIENT files. These data- set 
organizations are equivalent tc the 
options G(m) and R(r) available in 
Version 5 of the PL/I (F) compiler. The 
optimizing compiler will recognize and 
convert these forms of the options as 
shown in Figure B-2. 



Old form Converted tc 

G(m) V TP(M) RECSIZE(m) 

R(r) V TP(R) RECSIZE(r) 

Figure B-2. Teleprocessing environment 
options 



Error Correction 

The error correction logic differs from 
that used by the PL/I (F) compiler. 
Invalid programs that are compiled and 
corrected by the (F) compiler may net give 
the same results on the optimizing 
compiler. 



EXCLUSIVE Attribute 



The EXCLUSIVE attribute implies enly the 
RECORD attribute; DIRECT, UPDATE, and 
KEYED will apply only by default. 

The EXCLUSIVE attribute can be used in 
non-tasking programs, and jobs in the 
system can affect each other. 
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Facility 
Sort 

Checkpoint/Restart 



Return Code 
Dump 



Entry- point Name 

PLISRTA 
PLISRTB 
PLISRTC 
PLISRTD 
PLICKPT 
PLIREST 
PLICANC 
PLIRETC 
PLIDUMP 



Figure B-3. 



Operating system 
facilities 



In this example, the structure A has the 
LIKE attribute which refers to substructure 
C in structure B. B also contains 
substructure F with the LIKE attribute. 



Link -editing 



Programs translated by the optimizing 
compiler cannot be link-edited with object 
modules produced by the PL/I (F) compiler. 



Locked Records 



Expression Evaluation 



In a concatenation operation, a BINARY 
operand is converted to BIT if the other 
operand is BINARY or BIT. 



FIXED BINARY Expressions 



The length of FIXED BINARY constants and 
intermediate results with a precision less 
than 16 is 2 bytes. The UNSPEC built-in 
function returns a result whose length is 
16 bits. 



INITIAL Attribute 



The limitations on the length of DECLARE 
statements imposes some restrictions on the 
use of the INITIAL attribute. These 
restrictions are described under "statement 
Length" later in this appendix. 



The locking action takes place at the 
data set level. 

If an on-unit is entered as a result of 
a REWRITE or DELETE statenent, the 
record is unlocked if the on-unit is 
terminated by a GOTO statement as well 
as normal completion. 

The ERROR condition is raised if a file 
is closed while subtasks currently have 
records in it locked. 

A record is not locked due to "key not 
found" or "key outside data" conditions. 



Multitasking Programs 



In certain circumstances, it is possible 
for multitasking programs compiled by the 
PL/ I Optimizing Compiler to take longer to 
execute than corresponding programs 
compiled by the PL/I (F) Compiler. This 
situation can occur if a subtask, in which 
no files are opened, is repeatedly called. 



LIKE Attribute 



The optimizing compiler does not permit a 
substructure to have the LIKE attribute 
when another substructure within the major 
structure is the object of a further LIKE 
attribute. For example: 

DCL 



1 


A LIKE C, 


1 


B, 




2 C, 




3 D, 




3 E, 




2 F LIKE X, 


1 


X, 




2 Y, 




2 Z; 



NAME Option 



When using batched compilation to produce 
two object modules that will be combined 
into one load module, the NAME option 
should not be used in the EXEC statement, 
because the options in the PARM parameter 
apply to all procedures in the batch. 



Operating System Facilities 



The operating system facilities for 
sorting, for checkpoint/restart, for 
generating a return code, and for 
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obtaining a dump are all invoked by 
means of a CALL statement with the 
appropriate entry- point name; for 
example CALL PLISRTA. The entry point 
names, which are listed in Figure B-3 , 
have the BUILTIN attribute and need not 
be declared explicitly. 

The optimizing compiler does not 
recognize the entry names used by the 
PL/I '(F) compiler, that is, IHESRTx, 
IHESARC, IHEDUMx, and IHECKPT . Existing 
programs for the PL/I (F) compiler that 
use these entry names must be amended so 
that the DECLARE statements for them are 
removed completely. 



identical to that specified in a 
WRITE. . . KEYFROM, LOCATE. . .KEYFROM, or 
REWRITE FROM... KEY statement, the latter 
is moved into the record. 

READ, REWRITE, and DELETE statements are 
invalid for REGIONAL DIRECT OUTPUT 
files. 

There is no default record format for 
RECORD files (unless the file is 
associated with a DD DUMM¥ statement, in 
which case the default is U- format). If 
the record format is not specified, the 
UNDEFINEDFILE condition is raised. 



Pictures 



Redundant Expression Elimination 



Sterling picture data is not implemented. 
Therefore the following picture characters 
are not allowed: 

G, H, M, P, 6, 7, 8. 



Preprocessor 



The optimization process of eliminating 
redundant expressions could give rise to an 
incompatibility for (F) compiler programs 
that are recompiled by the optimizing 
compiler. If a program contains an 
expression, such as IF (A=D) | (C=D) TBEN,. . . 
such that the condition (A=D) is satisfied, 
the expression (C=D) is ignored. Hcwever, 
(C=D) might contain a function which, if 
not evaluated, could give rise to error. 



Text replaced by preprocessor statements 
does not have blanks appended to either 
end of the replacement value. 

A parameter descriptor list is not 
allowed in the declaration of a 
preprocessor variable with the ENTRY 
attribute. 



Return Codes 



The maximum return code that may be set 
using PLIRETC is 999. 



The RETURNS attribute may not be 
specified in a preprocessor DECLARE 
statement. 



Pseud ovariables 



For a varying string, the first 16 bits of 
the value of the UNSPEC pseud ovariable 
represent the current length of the string. 



Record I/O 



REWIND Option 

The optimizing compiler does not implement 
the REWIND option. Programs that use this 
option should be modified. Note that the 
function of the REREAD option implemented 
by the optimizing compiler is different to 
that of the REWIND option. The main 
difference is that the REREAD option 
overrides any DISP parameter and controls 
the positioning of the magnetic tape volume 
whereas the REWIND option specifies that 
the DISP parameter is to control the 
positioning of the magnetic tape volume 
according to the subparameters specified. 



• If READ. .. KEY is used with a sequential 
data set and no record with the 
specified key exists in the data set, 
the KEY condition is raised and the file 
is positioned at the next record in 
ascending sequence. 

• If an embedded key in a record is not 



Standard File SYSPRINT 



The default record characteristics are: 
record format = VBA, record length = 125, 
and block size = 129. The default number 
of buffers is two. Using the DCB parameter 
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of the DD statement, record format, record 
length, block size, and the number of 
buffers can be changed to any valid value. 

The following sequence: 

DCL SYSPRINT FILE; 



OPEN FILE (SYSPRINT) ; 

will cause the UNDEFINEDFILE condition to 
be raised. Omission of either or both 
statements will result in correct 
execution. The file should be declared 
implicitly or with the attributes STREAM 
and OUTPUT. 



Statements 



The approximate maximum number of 
statements in a program is 10,000, 



Statement Labels 



A label on a DECLARE statement is treated 
as if it were on a null statement. 



Statement Lengths 



The optimizing compiler has a restriction 
that any statement must fit into the 
compiler's work area. The maximum size of 
this work area varies with the amount of 
space available to the compiler. The 
limitations on the length of statements are 
given in Figure B-4. 



DCL 1 A, 

2 B(10,10) INIT(1,,2, 3, ...), 
2 C(10,100) INIT(dOOO) (0)), 
(D,E) CHAR(20) VAR, ... 

In this example, each line can be 
treated by the compiler as a separate 
DECLARE statement in order to accoirircdate 
it in the work area. The compiler will 
also treat in the same way the INITIAL 
attribute when it is followed by a list of 
items separated by commas that are net 
contained within parentheses. Each item 
may contain initial values that, when 
expanded, do not exceed the maximum length. 
The above also applies to the use of the 
INITIAL attribute in a DEFAULT statement. 

The (F) compiler can use up to 90K bytes 
for its work area. It is possible that 
programs with large DECLARE statements will 
not compile successfully on the optimizing 
compiler although they had compiled 
successfully on the (F) compiler. The 
following techniques are suggested to 
overcome this problem: 

• Increase the main storage available to 
the compiler, unless it already exceeds 
69K bytes. 

• Simplify the DECLARE statement so that 
the compiler can treat the statement in 
the manner described above. 

• Modify any lists of items following the 
INITIAL attribute so that individual 
items are smaller and separated by 
commas not contained in parentheses. 
For example, the following declaration 
is followed by an expanded form of the 
same declaration. The compiler can more 
readily accomodate the second 
declaration in its work area: 

1. DCL Y (1000) CHAR (8) 
INIT(dOOO) (8)'Y«); 

2. DCL Y (1000) CHAR (8) INIT 

((250) (8)'Y', (250)(8)'Y', 
(250) (8)'Y', (250) (8) •Y") ; 



Space Available Maximum Statement Length 



50K - 55K 
55K - 69K 
Over 69K 

Figure B-4. 



1012 characters 
1600 characters 
3400 characters 



Statement length 
limitations 



The DECLARE statement is an exception in 
that it can be regarded as a sequence of 
separate statements, each of which starts 
wherever a comma occurs that is not 
contained within parentheses. For example: 



Stream Transmission 



A filemark (or end of string mark for 
the STRING option) is a valid item 
delimiter for list-directed and data- 
directed input. An item thus delimited 
is processed intact, and ENDFILE (ERROR 
for string) is raised on attempting to 
read a further item from the file or 
string. 

After processing a GET LIST statement, a 
file is positioned to the next non-blank 
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character or, if this is a comma, to the 
character following the comma. A GET 
EDIT statement following a GET LIST on 
the same file must take into account the 
position of the file. 



The NAME condition (ERROR for the STRING 
option) is raised for all errors 
(including out of range subscripts) 
detected on the left-hand side of an 
item of data-directed input. 



Varying- length Strings 



The (F) compiler initializes a varying- 
length string to a null string, the 
equivalent of: 

STR = •«; 

whenever such a string is allocated. The 
optimizing compiler does not perform any 
initialization of varying -length strings, 
unless the INITIAL attribute is used. 



The COPY option causes all items to be 
copied, including any skipped by the 
SKIP option. A contextual declaration 
of SYSPRINT is caused if no file name is 
specified for the COPY option. 



When transmitting DATA -directed output 
to a PRINT file, data items less than or 
equal to the line size will rot be split 
between lines. Data items greater than 
the line size will, if possible, be 
split between the equals sign and the 
data value. 

Execution of a PUT statement in which 
the LINE option specifies the current 
line causes the END PAGE condition to be 
raised unless the current column is 1. 



WAIT Statement 



If a WAIT statement requires the completion 
of an inactive and incomplete event 
variable in a non-tasking program, then 
after any I/O event variables named in the 
same statement are completed, a message is 
printed and the program is terminated. In 
a TSO environment, control passes to the 
terminal. 
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Appendix C: Requirements for Problem Determination and 

APAR Submission 



When a member of IBM programming support 
personnel is called to examine the 
suspected malfunctioning of an IBM program 
product, he will first determine whether or 
not the malfunction really is a problem in 
the program product. If he decides that 
the program product is at fault, he roust 
then check to see if the fault is a known 
fault for which he can obtain an existing 
fix-up. If the fault is not known, he must 
refer the problem to the appropriate 
program maintenance group within IBM for 
analysis and correction. The process of 
referring a problem to IBM involves 
submitting a report known as an APAR 
(Authorized Program Analysis Report), which 
must be accompanied by material to enable 
the program maintenance personnel to 
analyze the problem. 

To enable IBM program maintenance 
personnel to analyze a problem, it must be 
possible to reproduce it at the IBM program 
maintenance center. It will therefore be 
essential to supply with the APAR the 
source program to enable the problem to be 
reproduced and analyzed. Faster resolution 
of the APAR may be possible if some or all 
of the material listed in Figure C-l is 
supplied and if the source program is 
reduced to the smallest, least complex form 
that still contains the problem. 

All listings that are supplied must 
relate to a particular execution of the 
compiler, in the case of a suspected 
compiler failure, or to the relevant link 
editing and execution steps, in the case of 
the failure of the PL/I program during 
execution. Listings derived from separate 
compilations or executions are of no value 
and may, in fact, be misleading to the 
programming support personnel. 



Original Source Program 



The original PL/I source program must be 
supplied in a machine -readable form such as 
a deck of punched cards or a reel of 
magnetic tape. The copy of the program 
supplied must be identical to the listing 
that is also supplied. 



the source program submitted should 
include, either as a card deck or on 
magnetic tape, the source module obtained 
by means of the compiler MDICK option. 

If the problem is known tc have occurred 
during preprocessing, a listing of the 
source program being preprocessed must be 
supplied, if the preprocessing involves 
the use of the 5SINCLUDE statement, a copy 
of the PL/I source statement module (s) 
included should be supplied in a machine- 
readable form. If source statement modules 
are not supplied in the original submission 
of the APAR, the APAR will be put into 
abeyance until they are supplied. 



Job Control Statements 



Listings of job control statements used to 
run the program must be supplied. For OS 
installations, any local cataloged 
procedures should be shown ir expanded 
form, obtained by specifying MSGLEVEL=1 in 
the JOB statement. Where there are a large 
number of job control statements, supply 
these also in a machine -readable fcrm such 
as on punched cards or on magnetic tape. 
This will assist the program maintenance 
personnel to reproduce the problem ircre 
quickly. 



Operating Instructions/Console Log 



In the case of an execution-time failure of 
a program that processes a number of data 
sets or that operates in a complicated 
environment, such as a teleprocessing 
application, it is essential that adequate 
description of the processing and the 
environment is given to enable it tc be 
recreated. Although it may be impossible 
to supply console logs and operating 
procedures, a complete description cf the 
application, the organization of the data 
sets, and adequate operating instructions 
are vital for the IBM program maintenance 
personnel to reproduce the problem. 



Use of the Preprocessor 



If the compilation includes preprocessing, 



Terminal Session Listing 



If a malfunction is detected during a 
conversational (TSO), session the entire 
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r 

| Material Required 


I 


Compiler option 


| When Required 


j Original source program 






1 C,E,T 


| Job Control statements 






1 C,E,T 


| Operating Instructions/ 
j Console Log 








| Terminal session listing 






1 T 


j LOGON procedure listing 






1 T 


j Listings: 

j Source listing 

| Cross-reference listing 

j Attribute table 

j Aggregate table 

j Storage table 

| Compiler options 




SOURCE (S) 
XREF (X) 
ATTRIBUTES (A) 
AGGREGATE (AG) 
STORAGE (STG) 
OPTIONS (OP) 


1 C,E,T 
1 C,E,T 
1 C,E,T 
1 C,E f T 
1 C,E,T 
1 C,E,T 


| Compiler terminal dump 




DUMP (DU) 


1 C,T 


j Linkage editor map 




MAP (linkage editor 
option) 


1 E,T 


j Execution -time dump 






1 E f T 


j User subroutines 






1 E,T 


j User data sets 






I E,T 


| Preprocessor input 
j listing 




INSOURCE (IS) 


1 P#T 


j Preprocessor output 




MDECK (MD) 


1 C,E,T 


j Partition /Reg ion size 






I C,E,T 


| List of applied PTFs 






1 C,E,T 


j Note: "C" indicates the requirements for a compile-time error; 

j "E" indicates requirements for an executicn-time error; 

j "P" indicates the requirements for a preprocessor error; 

j "T" indicates the requirements for conversational (TSO) error. 



L , J 

Figure C-l. Summary of requirements for APAR submission 



listing produced at the terminal, from 
LOGON to LOGOFF, must be supplied. If the 
failure occurs during conversational 
processing of a large program under TSO, it 
may be easier to obtain the program's 
output by listing the PRINT data set on a 
line printer. 



conversational (TSO) session, a listing of 
the LOGON procedure must be supplied to 
enable the session to be reproduced. 



Listings 



LOGON Procedure 



If a malfunction is detected during a 



A listing of the source program is 
essential. Other compiler- generated 
listings, while not essentia 1, # may assist 
in producing a faster resolution of the 
APAR. If any of the compiler options that 
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must be specified in order to obtain 
material for submission with an APAR have 
been deleted at system generation, they can 
be restored for temporary use by ireans of 
the compiler CONTROL option. 

If the failure occurs during 
conversational compilation of a large 
program under TSO, it may be easier to 
obtain the required listings by running the 
compilation in a background region. 
Alternatively, the output PRINT data set 
may be printed on a line printer. 



listing showing those members of the 
library that have PTF or local fixes, 
provided that when the fix was made, the 
correct system status index (SSI) was 
included in the library directory. 
However, if a module contains more than one 
temporary fix, only the last fix to te 
applied will be listed by the IMAPTFLS 
program . 



Submitting th e APAR 



Linkage Editor Map 



When a problem occurs at execution time, a 
linkage editor map that was obtained when 
the copy of the program that has failed was 
link edited is essential. The linkage 
editor map will be used in the analysis of 
the storage dump that must also be obtained 
when the program failed. 



Execution -time Dumps 



If the problem occurs during execution of 
the PL/ I program, a storage dump must be 
supplied. A dump can be obtained by using 
a stand-alone dump program or by using the 
the system SYSABEND or SYSUDUMP facilities. 
However, if possible, a formatted PL/I dump 
produced by the PL/I error -hand ling 
facilities should be provided. A PL/I dump 
is obtained by including the following 
statement in an ERROR on-unit that will be 
entered when the program fails: 

CALL PLI D UMP ( ' TFHB • ) ; 



Applied PTFs 



A list of any program temporary fixes (PTF) 
and local fixes (s/zaps) applied to either 
the compiler or its libraries must be 
supplied. The IBM service aid program 
IMAPTFLS, described in the publication OS 
Service Aids . Order No. GC28-6719, can be 
used to obtain from a program library a 



when submitting material for an APAR to 
IBM, ensure that any magnetic tapes and 
decks of punched cards that are supplied 
containing source programs, job stream 
data, data sets, or libraries are carefully 
packed and clearly identified. 

Each magnetic tape submitted should have 
the following information attached and 
visible: 

• The APAR number assigned by IBM. 

• The contents of the volume (source 
program, job control statements, cr 
data, etc.). 

• The recording mode and density. 

• All relevant information about the 
labels used for the volume and its data 
sets. 

• The record format and blocking sizes 
used for each data set. 

• The name of the program that created 
each data set. 

Each card deck submitted must have the 
following information attached and visible: 

• The APAR number assigned by IBM. 

• The contents of the card deck (scurce 
program, job control statements, or 
data, etc.). 

This information will ensure that a 
magnetic tape or card deck will not be lost 
if it becomes separated from the rest of 
the APAR material, and that its contents 
are readily accessed. 
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Appendix D: IBM System/360 Models 91 and 195 



This appendix explains how exceptions and 
interrupts in Models 91 and 195 are handled 
by the operating system. An exception is a 
hardware occurrence (such as an overflow 
error) which can cause a program interrupt. 
An interrupt is a suspension of normal 
program activities. There are many 
possible causes of interrupts, but the 
following discussion is concerned only with 
interrupts resulting from hardware 
exceptions. 

IBM System/ 360 Models 91 and 195 are 
high-speed processing systems in which more 
than one instruction may be executed 
concurrently. As a result, an exception 
may be detected and an interrupt occur when 
the address of the instruction which caused 
the exception is no longer held in the 
central processing unit. Consequently, the 
instruction causing the interrupt cannot be 
precisely identified. Interrupts of this 
type are termed imprecise . When an 
exception occurs, the machine stops 
decoding further instructions and ensures 
that all instructions which were decoded 
prior to the exception are executed before 
honoring the exception. Execution of the 
remaining decoded instructions may result 
in further exceptions occurring. An 
imprecise interrupt in which more than one 
except! on, has occurred is known as a 
multiple- exception imprecise interrupt . 

The optimizing compiler permits 
processing Of imprecise interrupts only 
when the compiler option IMPRECISE is in 
effect. This is useful when debugging a 
program. The effect of the option is: 

1. To cause the compiler to insert 

special "no-Operation" instructions at 
certain points in the program to 
localize imprecise interrupts to a 
particular segment of the program, 
thus ensuring that interrupt 
processing results in the action 
specified in the source program. 
These "no- operation" instructions are 
generated: 

• Before an ON-statement. 

• Before a REVERT statement. 

• Before internal code to set the 
SIZE condition. 

• Before internal code to change 
prefix options. 

• Between statements if GOSTMT or 



GONUMBER apply. 

For a null statement. (This 
feature provides the prcgranmer 
with source language control over 
the timing of program interrupts.) 



2. To provide facilities fcr: 



Detecting multiple-exception 
imprecise interrupts. 



Setting the value that is required 
by the ONCOUNT built-in function. 



Raising the appropriate PL/I 
conditions. 



The order of processing the exceptions 
is as follows: 



1. PL/I conditions in the order: 



UNDERFLOW 



FIXEDOVERFLOW or SIZE 

ERROR (if system action is required 
for either FIXEDOVERFLOW or SIZE) 

FINISH (if system action is required 
for the previous ERROR condition) 

OVERFLOW 

ERROR (if system acticn is required 
for OVERFLOW) 

FINISH (if system action is required 
for the previous ERROR condition) 

ZERODIVIDE 

ERROR (if system acticn is required 
for ZERODIVIDE) 

FINISH (if system acticn is required 
for the previous ERROR condition) 

Note : The conditions FIXEDOVERFLOW and 
SIZE cannot occur together, because the 
same hardware condition raises both of 
them. 
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2. Hardware exceptions in the order: 

data 

specification 

addressing 

protection 

Conditions and exceptions are raised in 
the above order until one of the following 
situations occurs: 

• A GO TO statement in an on-unit is 
executed. All other exceptions will 
then be lost. 

• The ERROR condition is raised. If the 
program is terminated as a result of 
this action (that is r system action 



causing the ERROR condition to be 
raised, followed by the FINISH 
condition) , messages will be printed to 
indicate the nature of the unprocessed 
exceptions. The exceptions theirselves 
will not be processed. 

When an interrupt results from multiple 
exceptions, only one of the PL/ I conditions 
is raised for each type of exception that 
occurred. 

When a multiple -exception imprecise 
interrupt occurs, the ONCOUNT built-in 
function provides a binary integer count of 
the number of exception types (that have 
PL/I on -conditions associated with them) 
that remain to be processed. If the 
ONCOUNT built-in function is used when only 
a single exception has occurred, or if it 
is used outside an on-unit, a count value 
of zero is indicated. 



212 OS PL/I Optimizing Compiler: Programmer's Guide 



Appendix E: Shared Library Cataloged Procedures 



The shared library is a PL/I facility that 
allows an installation to load PL/I 
resident library modules into the link pack 
area (LPA) so that they are available to 
all PL/I programs. This reduces space 
overheads . 



The resident library subroutines to be 
included in the shared library can be 
chosen by the installation; they must 
include the initialization routine, the 
error- handling routine, the open file 
routine, and all modules addressed from the 
TCA that are not identical for multitasking 
and non-multitasking programs. Further 
details of the shared library are given in 
the publications OS PL/ I Optimizing 
Compiler t Execution Logic and OS PL/I 
Optimizing Compiler: System Information . 



The routines in the shared library are 
held in two of three link-pack-area 
modules: IBMBPSM, and either IBMBPSL or 
its multitasking equivalent IBMTPSL. Each 
of the link- pack modules contains a number 
of library routines, and is headed by an 
addressing control block known as a 
transfer vector . IBMBPSM contains those 
modules in the shared library that are 
common to both multitasking and non- 
multitasking PL/I environments . IBMBPSL 
contains the non-multitasking versions of 
those modules that are not identical in 
multitasking and non- mult it asking PL/I 
environments. This module has a 
multitasking counterpart, IBMTPSL, which 
holds the multitasking versions of such 
modules. 

Two further modules are also involved in 
handling the shared library. These are the 
shared library addressing modules IBMBPSR 
and its multitasking counterpart IBMTPSR. 
One or other of these modules;, each of 
which has the alias PLISHRE, is link-edited 
with compiled code and held in the program 
region: IBMBPSR for non -multi tasking 
programs, or IBMTPSR for multitasking 
programs. IBMBPSR and its multitasking 
counterpart hold dummy entry points which 
duplicate the names of all entry points of 
modules within the shared library. 
References to such entry points in compiled 
code are resolved to the dummy entry points 
in IBMBPSR or IBMTPSR. 

You can use the shared library by using 
standard IBM- supplied cataloged procedures 
and overriding the link- edit and loader 
procedure steps. 



Execution when Using the Shared Libra ry 



Use of the shared library is specified by 
the linkage editor statement INCLUDE 
PLISHRE. PLISHRE is an alias for the 
program region modules IBMBPSR and IEMTPSR. 
The appropriate module will therefore be 
loaded by the linkage ^ editor (IBMBPSR for 
non -multi tasking programs; IBMTPSR fcr 
multitasking programs) . Ml compiled code 
external references to shared library 
module entry points are then resolved to 
the dummy entry points in IBMBPSR (cr 
IBMTPSR). Similarly WXTRNs in the program 
region module are resolved if compiled code 
issues an EXTRN for the entry point. 

A load module created for use with one 
shared library will not execute with a 
different shared library. Ycu will have to 
link- edit the object module again, 
including the dummy transfer vector nodule 
for the different shared library. 

You must remember that the linkage 
editor or loader require a large air cunt of 
main storage for external symbol dictionary 
tables while processing the dummy transfer 
vector module. If you specify SIZE=200K in 
the PARM field of your EXEC statement for 
the linkage editor or loader (and use a 
region or partition of equivalent size),, 
you will get sufficient main storage for 
processing with the largest possible shared 
library. 

Your PL/I program may take slightly 
longer to execute when using a shared 
library, because all library calls have to 
pass through the transfer vectors. 
However, your main storage requirements for 
a region will be greatly reduced if you 
have carefully selected your shared library 
modules to suit the operating environment. 



Multitasking considerations 



The shared library has been designed so 
that multitasking does not affect it. If 
PLI.TASK is specified before PLI.EASE, the 
linkage editor statement INCLUDE PLISHRE 
will result in the module IBMTPSR being 
loaded and linked in the program region. 
When control passes to the code following 
the IBMBPIR entry point in IBMTPSR, a 
request is made to the system to load the 
multitasking shared library module IBMTPSM, 
The program then runs in the 'isual manner. 
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with the multitasking modules. 

An installation may specify that it does 
not require either the multitasking or the 
non-multitasking modules in the shared 
library. However both multitasking and 
non-multitasking versions of the program 
region module will still be created. The 
module for the unwanted environment will be 
a dummy. This prevents problems should an 
INCLUDE PLISHRE statement be included in a 
program that is intended to run in the 
environment with no shared library. If 
this process was not carried out, such a 
statement could result in the incorrect 
environment being initialized. 



USING STANDARD IBM CATALOGED PROCEDURES 



Standard IBM- supplied cataloged procedures 
that use the linkage editor or loader (see 
Chapter 11) can be used to specify the 
shared library. This is done by overriding 
the SYSLIN DD statement in the link-edit or 
load-and-go procedure steps to ensure that 



the shared library addressing irodule 
IBMBPSR is the first module to be included 
by the linkage editor or loader and that 
its entry point in the resulting load 
module has the name PLISHRE. For example, 
the cataloged procedure PLIXCL requires the 
following statements to irake use cf the 
shared library. 



//STEP1 
//IKED. SYS IN 
INCLUDE 



EXEC PLIXCL 
DD * 
SYSLIB (PLISHRE) 



(add further input here) 

/* 

You can add other linkage-editor control 
statements by placing theirs as indicated. 
For example, to give the resulting load 
module the name MINE, add the statement: 

NAME MINE(R) 

between the ENTRY and /* statements. 
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Appendix F: Programming Example 



This appendix, consisting of a PL/I sample 
program, illustrates all the components of 
the listings produced by the compiler and 
the linkage editor. The listings 
themselves are described in chapters 4 and 
5. 



statement. 

Most pages of the listings contain brief 
notes explaining the contents of the pages. 



The function of the program is fully 
documented in both the preprocessor input 
and the source listing by means of PL/I 
comments. These comments consist of lines 
of text each preceded by /* and followed by 
*/. Note that the /* must not appear in 
columns 1 and 2 of the input record because 
it will be taken as a job control delimiter 



TRANSIENT LIBRARY MODULES IN THE LINK 
PACK AREA 



Any module in the PL/I Transient Library 
may be placed in the link pack area (LPA) 
without any change in procedure. 
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PL/I OPTIMIZING COMPILER 



VERSION 1 RELEASE 2.0 



TIME: 21.15.03 



DATE: 13 APR 73 



PAGE 



OPTIONS SPECIFIED (V) 
AG,A,C,ESD,GS,LIST,M,MAP, OF, IS, STG, SYN, X,MAR (2, 72, 1) ,LC(55) 



OPTIONS USED (2) 



AGGREGATE 

ATTRIBUTES 

COMPILE 

ESD 

GOSTMT 

INSOURCE 

LIST 

LMESSAGE 

MACRO 

MAP 

NEST 

OBJECT 

OFFSET 

OPTIONS 

SOURCE 

STMT 

STORAGE 

SYNTAX 

XREF 



NOCOUNT 

NODECK 

NOFLOW 

NOGONUMBER 

NOIMPRECISE 

NOINCLUDE 

NOMARGINI 

NOMDECK 

NONUMBER 

NOTERMINAL 



CHARSET ( 60 , EBCDIC) 
FLAG (I) 
LINECOUNTC55) 
MARGINS(2,72,1) 
OPTIMIZE (TIME) 
SEQUENCE (7 3, 8 0) 
SIZE(10158U) 



Start of the compiler listing. 

(1) List of options specified in the 
PARM parameter of the EXEC 
statement. 

(2) List of options used, whether 
obtained by default, or by being 
specified explicitly. 



c 
rt> 



PL/I OPTIMIZING COMPILER 



/***** PL/I SAMPLE PROGRAM. *****/ 



PAGE 



PREPROCESSOR INPUT 



LINE 
1 



/***** PL/I SAMPLE PROGRAM. *****/ 



00269040 



> 

(D 
3 



2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 



%/++***+*+***********+**+***++******+*+*+***+*******+**+******+******/ 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



USES COMPILE-TIME PREPROCESSOR TO MODIFY PL/I (F) SOURCE FOR 
USE WITH THIS COMPILER. THE PREPROCESSOR STATEMENTS FOLLOWING 
COULD BE PLACED ON A LIBRARY AND USED TO MODIFY SEVERAL SOURCE 
PROGRAMS BY MEANS OF THE PREPROCESSOR %INCLUDE STATEMENT. THEY 
PERFORM THE FOLLOWING FUNCTIONS: 



1. CONVERT CALLS TO FOLLOWING PL/I (F) IHE. 



3. 



ROUTINES TO THE 



EQUIVALENT NEW PLI... 
IHEDUMP/J/C/T 
IHESRTA/B/C/D 
IHECKPS/T TO 
IHERESN/T TO 
IHESARC/IHETSAC 



. ROUTINES- 

TO PLIDUMP, 

TO PLISRTA/B/C/D, 

PLICKPT, 

PLIREST/PLICANC, 

: TO PLIRETC. 



TO INCLUDE 
FUNCTIONS( WHICH 



CHANGE FIRST DECLARE/DCL STATEMENT FOUND 

BUILTIN ATTRIBUTE FOR FOLLOWING BUILT-IN 

DO NOT TAKE ARGUMENTS, AND SO &RE NOT IMPLICITLY DECLARED 

BUILTIN FOR THIS COMPILER - AS THEY WOULD BE FOR PL/I (F))- 

DATE, TIME, ONCODE, ONCHAR, ONSOURCE, ONLOC, 

ONFILE, ONKEY, EMPTY, NULL. 
NOTE: THE ONCOUNT BIF IS OMITTED FROM THIS LIST, 6 IS USED 

LATER TO SHOW THE EFFECT OF NOT DECLARING IT BUILTIN. 

ANY REFERENCES TO IHE ROUTINES MUST BE REMOVED 

FROM DECLARE STATEMENTS BEFORE THE SOURCE PROGRAM IS 

PREPROCESSED, OTHERWISE FAILURES MAY OCCUR WHEN THE 

CONVERTED PROGRAM IS LINK-EDITED. 

CHANGE 'NULLO* TO 'NULL' - THERE IS NO NULLO BUILTIN 
FUNCTION FOR THIS COMPILER; NULL MUST BE USED BOTH WITH 
POINTER AND OFFSET VARIABLES. 



*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
V 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 



/*****+*+******#*♦****+*++****************+******+****+********+****/ 



00269050 
00269060 
00269070 
00269080 
00269090 
00269100 
00269110 
00269120 
00269130 
00269140 
00269150 
00269160 
00269170 
00269180 
00269190 
00269200 
00269210 
00269220 
00269230 
00269240 
00269250 
00269260 
00269270 
00269280 
00269290 
00269300 
00269310 
00269320 
00269330 
00269340 
00269350 
00269360 
00269370 
00269380 



Source statements for the sample 
program, exactly as they appear in the 
input stream. These statements form 
the input data for the preprocessor. 
Preprocessor statements are identified 
by the % symbol. 

1 . The first line of the input is 
included as part of the heading 
for all pages of the preprocessor 
and compiler listing. 

2. Each input record is numbered 
sequentially. 

3. If an input record has a sequence 
number, this number is printed. 



H 

oo 
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/***** PL /i SAMPLE PROGRAM. *****/ 



PAGE 



s 

H« 
N 

H- 
3 
iQ 

O 
O 
3 
•O 
H- 
H-* 
fl> 
H 



LINE 
36 
37 

38 
39 

40 



41 

43 
44 



DCL (IHEDUMP, IHEDUKJ, IHEDUMC, IHEDUMT, DECLARE, DCL, 

IHECKPT, IHECKPS) ENTRY; 

DCL (IHESRTA,, IHESRTB, IHESRTC, IHESRTD, IHEREST, 

IHERESN, IHESARC, IHETSAC, NULLO) CHAR; 

DCL COUNT FIXED; 



COUNT = 

DEACTIVATE DECLARE, DCL 
ACTIVATE DECLARE, 

DCL NORESCAN 



/* FIRST-TIME-IN SWITCH. 



00269390 
00269400 

00269410 
00269420 

00269430 



*/;00269440 



/* ENSURE MODIFIED STATEMENTS */; 00269450 
/* ARE NOT RESCANNED DURING */ 00269460 
/* PREPROCESSOR REPLACEMENT. */; 00269470 



•a 
o 
h 



c 

d 
(ft 
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/***** pl/! SAMPLE PROGRAM. *****/ 



PAGE 



LINE 
15 
46 
47 
48 
49 
50 
51 
52 
53 



X DECLARE: DCL: 



/* GENERATE BUILTIN DECLARES. */ 00269480 



PROC RETURNS (CHAR) ; 
COUNT = COUNT + 1 
IF COUNT = 1 

THEN RETURNCDCL (DATE, TIME, ONCHAR, ONSOURCE, ONCODE, ' 
' ONLOC, ONFILE, ONKEY , EMPTY, NULL) BUILTIN, 
' CKPT_RETC FIXED BIN ( 31) , ■ ) ; 
ELSE RETURN ( ' DCL ' ) ; 
END; 



/* COUNT = 1 IF 1ST TIME IN. 



II 



00269490 
*/;00269500 
00269510 
00269520 
00269530 
00269540 
00269550 
00269560 



54 
55 
56 
57 
58 
59 



% IHEDUMP: IHEDUMJ: IHEDUMC: IHEDUMT: /* REPLACED BY CALL TO */ 00269570 

PROC(ID#) RETURNS (CHAR) /* PLIDUMP ROUTINE, INCLUDING */; 00269580 

DCL ID# CHAR /* 0RI3INAL ID(IF PRESENT). */; 00269590 

IF ID# = * ■ THEN RETURNC PLIDUMP* ); 00269600 

ELSE RETURN ('PLIDUMPC 'TFC A",** ' || ID# || ■'•)') ;00269610 

X END; 00269620 



> 

•O 

3 
Qi 



60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 



71 
72 
73 
74 
75 
76 
77 
78 



ARG4) 



_ t i • 



r»nv» • • 



IHECKPS: IHECKPT: 

PR0C(ARG1', ARG2, ARG3, 

RETURNS (CHAR) 
DCL (ARGl, ARG2, ARG3, 
IF ARGl = * ' THEN AR31 
IF ARG2 = •• THEN ARG2 
IF ARG3 = ' * THEN AR33 
IF ARG4 = * ' THEN ARG4 = * CKPT_RETC* ; 
RETURNCPLICKPTC || ARGl |j ',* || AR32 
| j ARG3 || ' , ' || ARG4 
END; 



/* CHANGE TO PLICKPT. PL/KF) 
/* DEFAULTS GENERATED WHERE 
/* NO ARGUMENTS ORI3INALLY. 
ARG4) CHAR; 



SYSCHK 



PS' 



II ')•); 



IHESRTA 
IHESRTB 
IHESRTC 
IHESRTD 
IHEREST 
IHERESN 
IHESARC 
IHETSAC 



•PLISRTA' 
' PLISRTB* 
•PLISRTC 
'PLISRTD* 
'PLIREST' 
'PLICANC* 
'PLIRETC 
•PLIRETC 



/* 


REPLACE 


/* 


CALLS TO 


/* 


IHE 


/* 


ROUTINES 


/* 


BY 


/* 


CALLS TO 


/* 


PLI 


/* 


ROUTINES 



*/ 00269630 
*/ 00269640 
*/;00269650 
00269660 
00269670 
00269680 
00269690 
00269700 
00269710 
00269720 
00269730 



*/;00269740 
*/;00269750 
*/;00269760 
*/; 00269770 
*/;00269780 
*/;00269790 
*/;00269800 
*/;00269810 



79 

80 



%/* 



THERE IS NO NULLO BUILTIN FUNCTION FOR THIS COMPILER; 
NULL MUST BE USED INSTEAD. 



00269820 
*/;00269830 



81 



NULLO = 'NULL'; 



00269840 
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/***** PL/I SAMPLE PROGRAM. *****/ 



P&3E 



8 

H 
ft 



P. 
N 

5 



o 

3 

(I> 



H 
O 



LINE 
82 



83 
8«J 



85 

86 

87 
88 
89 



90 
91 
92 
93 
94 



%/* END OF PREPROCESSOR STATEMENTS; SOURCE STATEMENTS FOLLOW HERE: */; 00269850 



SAMPLE: 



PROC OPTIONS (MAIN); 

DECLARE (PDATE, PTIME) CHAR(6); 

DECLARE CVAR CHAR (255) VAR; 

DCL 1 BINVAR, 

2 RETCODE FIXED BIN(31,0), 
2 FBVAR FIXED BIN; 



00269860 
00269870 



00269880 

00269890 

00269900 
00269910 
00269920 



PDATE = DATE; 00269930 

PTIME = TIME; 00269940 

PUT SKIP EDITC SAMPLE PR03RAM: DATE = ' , PDATE, ' , TIME = " , 00269950 

PTIME) (A(23) f P'99/99/99", A(9), P" Z9. 99. 99' ) ; 00269960 

RETCODE = 0101; 00269970 



c 
fl> 



95 
96 
97 



98 
99 

100 
101 
102 

103 
104 
105 
106 
107 
108 



ON ERROR 



BEGIN; 



CALL IHEDUMP; 



/* THESE STATEMENTS ILLUSTRATE PREPROCESSOR REPLACEMENT AND USE OF 
BUILTIN FUNCTIONS. THEY WILL NEVER BE EXECUTED. 

CALL IHEDUMJ(127); 
CALL IHEDUMC (RETCODE); 
CALL IHEDUMT; 

FBVAR = ONCODE; 
CVAR = ONCHAR; 
CVAR = ONSOURCE; 
CVAR = ONLOC; 
CVAR = ONFILE; 
CVAR = ONKEY; 



00269980 
00269990 
00270000 



00270010 
♦/00270020 

00270030 
00270040 
00270050 

00270060 
00270070 
00270080 
00270090 
00270100 
00270110 
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PAGE 



LINE 
109 
110 
111 

112 
113 



/* THIS STATEMENT, WHICH WILL NEVER BE EXECUTED, OSES 'ONCODNT" WHICH 00270120 
IS NEITHER EXPLICITLY NOR IMPLICITLY DECLARED BUILTIN. THE EFFECT 00270130 
IS SHOWN IN THE ATTRIBUTE LISTIN3 AND DIAGNOSTIC MESSAGES. */00270140 



FBVAR = ONCOUNT; 



END; 



00270150 
00270160 



3 
Qi 



*i 



111 

115 
116 

117 
118 

119 
120 
121 
122 

123 
124 
125 

126 
127 
128 
129 
130 
131 
132 
133 
13U 

135 
136 
137 

138 



/* THIS IS A DUMMY PROCEDURE TO ILLUSTRATE OTHER PREPROCESSOR 
REPLACEMENTS/NON- IMPLICITLY DECLARED BUILTIN FUNCTIONS. 
IT WILL NEVER BE EXECUTED. 



DUMMY : 



A: 
B: 



PROC; 



DCL 



AVAR AREA BASED (PVAR), 
OVAR OFFSET (AVAR), 
A ENTRY RETURNS (CHAR( 80)), 
SIZE FIXED BIN (31,0); 



AVAR = EMPTY; 
PVAR = NULL; 
OVAR = NULLO; 

CALL IHESRTA ( ■ ARG1 ' , ' ARG2 * , 
CALL IHESRTBCARG1', 'AR32', 
CALL IHESRTC ( ' ARG1 • , ' ARG2 ' , 
CALL IHESRTDC'ARGl', 'AR32', 
CALL IHECKPS ( ' ARG1 * , • ARG2 ■ , 
CALL IHECKPT; /* CHECKPOINT 
CALL IHEREST; 
CALL IHERESN; 
CALL IHETSAC(RETCODE); 



SIZE, RETCODE) ; 



/* 



SIZE, 


RETCODE, 


A) ; /* O 


SIZE, 


RETCODE, 


B) ; /* R 


SIZE, 


RETCODE, 


A, B) ; /* T 


'PS', 


RETCODE) , 


; /* CHECKPOINT 


*/ 




/* FORCE RESTRT 
/* CANCEL CKPT 



/* SET RETURN CODE (TASKING) 



PROC RETURNS(CHAR(80)); END; 

PROC ( RECORD) ; DCL RECORD CHAR (80); 

END DUMMY; 



END; 



/* DUMMY EXIT 
/* PROCEDURES 
/* FDR SORT. 



00270170 

00270180 

*/00270190 

00270200 
00270210 

00270220 
00270230 
00270240 
00270250 

00270260 
00270270 
00270280 

♦/00270290 
+/00270300 
+/00270310 
♦/00270320 
♦/00270330 
002703*0 
♦/00270350 
♦/00270360 
♦/00270370 

+/00270380 
*/00270390 
♦/00270400 

00270410 



139 

mo 



CALL I HESARC( RETCODE); /* SET RETURN CODE(NONTASKING) +/00270420 
PUT SKIP LISTCEND SAMPLE PR03RAM'); 00270430 



141 



END SAMPLE; 



00270440 



to 
to 
to 



O 

w 

H 

o 

3 
H« 
N 
H- 
3 

O 
O 
3 
•O 
H- 
H 
<D 
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PREPROCESSOR DIAGNOSTIC MESSAGES 



/***** PL/I SAMPLE PROGRAM. *****/ 



PAGE 7 



© © © 



ERROR ID L LINE MESSAGE DESCRIPTION 



SEVERE AND ERROR DIAGNOSTIC MESSAGES 



IEL0217I E 97 



IEL0217I E 102 



IEL0217I E 131 



MISSING LEFT PARENTHESIS FROM ARGUMENT LIST FOR PROCEDURE 'IHEDUMP* 
ARGUMENTS . 

MISSING LEFT PARENTHESIS FROM ARGUMENT LIST FOR PROCEDURE 'IHEDUMT' 
ARGUMENTS . 

MISSING LEFT PARENTHESIS FROM ARGUMENT LIST FOR PROCEDURE • IHECKPT' 
ARGUMENTS. 



PROCEDURE INVOKED WITHOUT 



PROCEDURE INVOKED WITHOUT 



PROCEDURE INVOKED WITHOUT 



t3 
H 
O 



C 
fl> 



WARNING DIAGNOSTIC MESSAGES 



IEL0184I W 97 
IEL018«II W 102 
IEL0181I W 131 



TOO FEW ARGUMENTS TO FUNCTION 'IHEDUMP*. 
TOO FEW ARGUMENTS TO FUNCTION 'IHEDUMT*. 
TOO FEW ARGUMENTS TO FUNCTION * IHECKPT'. 



NULL STRINGS PASSED AS MISSING ARGUMENTS. 
NULL STRINGS PASSED AS MISSING ARGUMENTS. 
NULL STRINGS PASSED AS MISSING ARGUMENTS. 



END OF PREPROCESSOR DIAGNOSTIC MESSAGES 



Diagnostic messages generated by the 
preprocessor. All messages generated 
by the optimizing compiler (including 
the preprocessor) are documented in 
the publication OS Optimizing Compiler ; 
Messages . 

(T) "ERROR ID" This identifies the 
message as originating from the 
optimizing compiler (IEL) , and 
gives the message number. 

(l) "L" This is the severity level of 
the message. 

(3) "LINE" This gives the number of 
the line in which the error 
occurred. 
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/***** pl/i SAMPLE PROGRAM. *****/ 



© 

STMT LEV NT 



SOORCE LISTING 



/***** PL/I SAMPLE PROGRAM. 
SAMPLE: 

PROC OPTIONS (MAIN); 



© 



© 

R 



002690*0 
00269860 
00269870 



DCL (DATE, TIME, ONCHAR,ONSOORCE,ONCODE,ONLOC,ONFILE,ONKEY, EMPTY, 00269880 2 

NOLL) BDILTIN, CKPT RETC FIXED BIN(31), (PDATE, PTIME) CHAR(6); 00269880 1 



DCL CVAR CHAR (255) VAR; 



00269890 2 



BINVAR, 
2 RETCODE FIXED BIN (3 1,0), 
2 FBVAR FIXED BIN; 



00269900 1 

00269910 

00269920 



PDATE = DATE; 00269930 

PTIME = TIME; 00269940 

POT SKIP EDIT ('SAMPLE PROGRAM: DATE = ", PDATE, *, TIME = *, 00269950 

PTIME) (A(23), P'99/99/99', A(9), P' Z9. 99.99' ) ; 00269960 

RETCODE = 0101; 00269970 



9 10 ON ERROR 

BEGIN; 
10 2 CALL PLIDOMP; 



00269980 x-s 
00269990 \Z) 
00270000 IE 



/* THESE STATEMENTS ILLOSTRATE PREPROCESSOR REPLACEMENT AND OSE OF 
BOILTIN FONCTIONS. THEY WILL NEVER, BE EXECOTED. 



00270010 
♦/00270020 



> 

•a 
to 

s 
a. 



11 


2 





12 


2 





13 


2 





14 


2 





15 


2 





16 


2 





17 


2 





18 


2 





19 


2 






CALL PLIDOMP riFCA',' 127'); 
CALL PLIDOMP ( • TFCA ' , ' RETCODE ' ) 
CALL PLIDOMP; 

FBVAR = ONCODE; 
CVAR = ONCHAR; 
CVAR = ONSOORCE; 
CVAR = ONLOC; 
CVAR = ONFILE; 
CVAR = ONKEY; 



00270030 1 
00270040 1 
00270050 IE 

00270060 
00270070 
00270080 
00270090 
00270100 
00270110 



•0 
H 
O 



\Q 







Source listing. This is the output 
from the preprocessor and the input to 
the compiler. All the preprocessor 
statements have been executed and all 
preprocessor comments have been 
deleted 

(T) Statement nesting levels. 

(i) Line numbers brought forward from 
the preprocessor input. 

\$) Maximum depth of replacement. 

(4) "E" in this column indicates that 
an error has occurred during a 
replacement attempt. 
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H- 

3 

H- 
N 
P- 

3 

ia 

o 
o 

3 
•O 
H- 
M 
CD 
K 



H 

o 



c 



STMT LEV NT 



20 
21 



22 



23 



2 
2 



2 



/* THIS STATEMENT, WHICH WILL NEVER BE EXECUTED, USES 'ONCOUNT' WHICH 00270120 
IS NEITHER EXPLICITLY NOR IMPLICITLY DECLARED BUILUN. THE EFFECT 00270130 
IS SHOWN IN THE ATTRIBUTE LISTING AND DIAGNOSTIC MESSAGES. */00270140 



FBVAR = ONCOUNT; 



END; 



/* THIS IS A DUMMY PROCEDURE TO ILLUSTRATE OTHER PREPROCESSOR 
REPLACEMENTS/NON-IMPLICITLY DECLARED BUILTIN FUNCTIONS. 
IT WILL NEVER BE EXECUTED. 



DUMMY: 



24 


2 





25 


2 





26 


2 





27 


2 





28 


2 





29 


2 





30 


2 





31 


2 





32 


2 





33 


2 





34 


2 





35 


2 





36 


2 


A: 


38 


2 


B: 


41 


2 





42 


1 





43 


1 






PROC; 



DCL 



AVAR AREA BASED(PVAR), 
OVAR OFFSET (AVAR) , 
A ENTRY RETURNS (CHAR(80)), 
SIZE FIXED BIN(31,0); 



AVAR = EMPTY; 
PVAR = NULL; 
OVAR = NULL; 

CALL PLISRTACARGl', 'AR32', SIZE, RETCODE) ; /* S 

CALL PLISRTB ( * ARG1 ' , 'ARG2', SIZE, RETCODE, A); /* O 

CALL PLISRTCCARGl', 'AR32', SIZE, RETCODE, B) ; /* R 

CALL PLISRTDCARG1V, , ARG2', SIZE, RETCODE, A, B) ; /* T 

CALL PLICKPTCARSl*, , AR32«, 'PS*, RETCODE); /* CHECKPOINT 
CALL PLICKPTCSYSCHK', ", 'PS', CKPT RETC) ; /* CHECKPOINT 



00270150 
00270160 



00270170 

00270180 

♦/00270190 

00270200 
00270210 

00270220 1 
00270230 
00270240 
00270250 

00270260 
00270270 
00270280 1 



CALL PLIREST; 
CALL PLICANC; 
CALL PLIRETC (RETCODE); 



/* 



/* FORCE RESTRT 
■/* CANCEL CKPT 
SET RETURN CODE (TASKING) 



*/00270290 
♦/00270300 
*/00270310 
♦/00270320 
♦/00270330 
♦/00270340 
00270340 
*/00270350 
♦/00270360 
♦/00270370 



PROC RETURNS ( CHAR ( 80 ) ) ; END ; 
PROC(RECORD); DCL RECORD CHAR(80); 
END DUMMY; 



/* DUMMY EXIT */00270380 

/* PROCEDURES */00270390 

END; /* FOR SORT. */00270400 

00270410 



CALL PLIRETC (RETCODE) ; /* SET RETURN CODE (NONT ASKING) 
PUT SKIP LIST ('END SAMPLE PROGRAM*); 



1 
1 
1 
1 
1 
IE 

1 
1 
1 



♦/00270420 1 
00270430 



44 



1 



END SAMPLE; 



00270440 
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© © 

DCL NO. IDENTIFIER 



36 



ATTRIBUTE AND CROSS-REFERENCE TABLE 



ATTRI BOTES AND REFERENCES 





©ENT 
28, 



ENTRY RETURNS (CHARACTER (80)) 
30 



23 



AVAR 



BASED (PVAR) ALIGNED AREA (1000) 
24 



38 



B 



ENTRY RETURNS (DECIMAL /* SINGLE */ FLOAT (6)) 
29,30 



BINVAR 
CKPT RETC 



AUTOMATIC /* STRUCTURE */ 



AUTOMATIC ALIGNED BINARY FIXED (31,0) 
32 



CVAR 



AUTOMATIC UNALIGNED CHARACTER (255) VARYING 
15,16,17,18,19 



DATE 



BUILTIN 
5 



22 
2 



DUMMY 
EMPTY 



ENTRY RETURNS (DECIMAL /* SIN3LE */ FLOAT (6)) 



BUILTIN 
24 



FBVAR 



/* IN BINVAR */ AUTOMATIC ALIGNED BINARY FIXED (15,0) 
14,20 



NULL 



BUILTIN 
25,26 



> 

a 

3 
Qj 

K 



H 
O 
iQ 
H 
0) 
3 
3 
H« 
3 
iQ 

W 
X 

0) 

3 






ONCHAR 



ONCODE 



******** ONCOUNT 



© 



ONFILE 



BUILTIN 
15 



BUILTIN 
14 



AUTOMATIC ALIGNED DECIMAL /* SINGLE */ FLOAT (6) 
20 



BUILTIN 
18 



Attributes and Cross-reference Table. 

(Y) Number of the statement in the 
source listing in which the 
identifier is explicitly declared. 

(2) Asterisks indicate an undeclared 
identifier; all of its attributes 
are implied or supplied by 
default. 



(l) All identifiers used in the 
program listed in alphabetic 
order. 



© 



4J Declared and default attributes 
are listed. This list also 
includes descriptive comments. 

(5) Cross references. These are the 
^^^ numbers of all other statements in 
which the identifier appears. 
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O 

CO 

H 

o 

*a 
ft 

H« 
3 
H« 
N 
H- 

o 
o 

3 

H- 
M 
fl) 
M 



•13 
H 


% 
01 

3 
3 
fl> 
H 



DCL NO. IDENTIFIER 



Q» 



2 


ONKE5T 


2 


ONLOC 


2 


ONSOORCE 


23 


OVAR 



PDATE 



******** PLICANC 



******** PLICKPT 



******** PLIDUMP 



******** PLIREST 



******** PLIRETC 



ATTRIBUTES AND REFERENCES 



BDILTIN 
19 

BUILTIN 
17 

BUILTIN 
16 

AUTOMATIC ALIGNED OFFSET (AVAR) 
26 

AUTOMATIC UNALIGNED CHARACTER (6) 
5,7 

BUILTIN 
34 

BUILTIN 
31,32 

BUILTIN 
10,11,12,13 

BUILTIN 
33 

BUILTIN 

42 

35 



******** PLISRTA 



BDILTIN 
27 



******** PLISRTB 



BUILTIN 
28 



******** PLISRTC 



BUILTIN 
29 



******** PLISRTD 



BUILTIN 
30 



PTIME 



AUTOMATIC UNALI3NED CHARACTER (6) 
6,7 



******** pvar 



AUTOMATIC ALIGNED POINTER 
24,25 
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DCL NO. IDENTIFIER 



ATTRIBUTES AND REFERENCES 



39 
4 

1 
23 



RECORD 
RETCODE 

SAMPLE 
SIZE 



/* PARAMETER */ UNALIGNED CHARACTER (80) 

/* IN BINVAR */ AUTOMATIC ALIGNED BINAR5T FIXED (31,0) 

8.42 

27,28,29,30,31,35 

EXTERNAL ENTRY RETURNS (DECIMAL /* SINGLE */ FLOAT (6)) 

AUTOMATIC ALIGNED BINARY FIXED (31,0) 
27,28,29,30 



******** SYSPRINT 



EXTERNAL FILE PRINT 
7,43 



TIME 



BUILTIN 
6 



00 






* 

rt 
H* 
S 
M- 
N 
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© 

DCL NO. 



© 

IDENTIFIER 



BINVAR 

RETCODE 

FBVAR 



/***** PL/I SAMPLE PROGRAM. *****/ 



AGGREGATE LEN3TH TABLE 



© 



LVL 



DIMS 



PAGE 1 3 



OFFSET ELEMENT TOTAL 

LENGTH. LENGTH. 



SUM OF CONSTANT LENGTHS 



© 



O 
O 

a 
IT 



H 

H 

9 



Q> 
A 



Aggregate Length Table. 



© 



1) Number of the statement in which 
the aggregate is declared, or, for 
a controlled aggregate , the number 
of the associated ALLOCATE 
statement . 

(?) The elements of the aggregate as 
declared. 

\2J Length of each element of the 
aggregate . 

Qf) Sum of the lengths of aggregates 
whose lengths are constant. 
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STORAGE REQUIREMENTS 

© 

BLOCK, SECTION OR STATEMENT TYPE 



♦SAMPLEl 

♦SAMPLE2 

SAMPLE 

9 

DUMMY 

A 

B 



PROGRAM CSECT 
STATIC CSECT 
PROCEDURE BLOCK 
ON UNIT 

PROCEDURE BLOCK 
PROCEDURE BLOCK 
PROCEDURE BLOCK 



® 




© 




LENGTH 


(HEX) 


DSA SIZE 


(HEX) 


2156 


86C 






788 


314 






454 


1C6 


552 


228 


630 


276 


224 


EO 


834 


342 


232 


E8 


106 


6A 


184 


B8 


124 


7C 


200 


C8 



> 
a 

S 
X 



H 

& 

H 

a 

3 
iQ 

Ed 
X 

01 

a 



Storage requirements. This table gives 
the main storage requirements for the 
program. These quantities do not 
include the main storage that will be 
required by the resident and transient 
library subroutines that will be 
included by the linkage editor or 
loaded dynamically during execution. 



© 

© 
© 



© 



Name of the block, section, or 
number of the statement in the 
program. 

Description of the block, section, 
or statement. 

Length in bytes of the storage 
areas in both decimal and hexa- 
dec imal not at i on . 



4) Length in bytes of the dynamic 
storage area (DSA) in both 
decimal and hexadecimal notation. 



to 

(O 



PL/I OPTIMIZING COMPILER 



/***** PL/I SAMPLE PROGRAM. *****/ 
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EXTERNAL SYMBOL DICTIONARY 

© © © © 



© 



SYMBOL 

PLI START 

♦SAMPLE1 

♦SAMPLE2 

PLI TABS 

PLIXOPT 

PLI FLOW 

PLICODNT 

IBMBPIRA 

IBMBPIRB 

IBMBPIRC 

PLI CALL A 

PLICALLB 

PLIMAIN 

IBMBKCPC 

IBMBKCPA 

IBMBKCPB 

IBMBKCPA 

IBMBKCPA 

IBMBKSTD 

IBMBKSTA 

IBMBKSTC 

IBMBKSTA 

IBMBKSTB 

IBMBKSTA 

IBMBKSTA 

IBMBKDMA 

IBMBPRCA 

IELCGOA 

IELCGOB 

IBMBSEDA 

IBMBSIOA 

IBMBCCSA 

IBMBCHFD 

IBMBCODE 

IBMBCTHD 

IBMBCUID 

IBMBEOCA 

IBMBEOLA 

IBMBJDTA 

IBMBJTTA 

IBMBOCLA 

IBMBOCLC 

IBMBSEDB 

IBMBSEOA 

IBMBSIOE 

IBMBSIOT 

IBMBSLOA 



TYPE 

SD 
SD 
SD 
WX 
WX 
WX 
WX 
ER 
ER 
ER 
LD 
LD 
SD 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
SD 
SD 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
ER 
WX 
WX 
ER 
WX 
WX 
ER 



ID 

0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
000A 



000B 
000C 
000D 
000E 
000F 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
001A 
001B 
001C 
001D 
001E 
001F 
0020 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0028 
0029 
002A 
002B 
002C 
002D 



ADDR 

000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000006 
00000A 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 



LENGTH 

000044 
00086C 
000314 



000008 



000072 
000070 



External symbol dictionary. 



© 
© 



© 
© 



"SYMBOL" A list of all the 
external symbols that make up the 
object module. 

"TYPE" Type of external symbol as 
follows : 

CM Common area. 

ER External reference. 

LD Label definition. 

PR Pseudo-register. 

SD Section definition. 

WX Weak external reference. 
Full definitions of all these 
terms are given in chapter 4 . 

"ID" All entries, except LD-type 
entries, are identified by a 
hexadecimal number. 



4 J "ADDR" Address (in hexadecimal) 
of LD-type entries only. 

(?) "LENGTH" Length in bytes (in 
hexadecimal) of LD, CM, and PR 
type entries only. 
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IBMBSPLA 


ER 


002E 


000000 




IBMBSPOA 


ER 


002F 


000000 




IBMBCKDD 


ER 


0030 


000000 




IBMBSXCA 


WX 


0031 


000000 




IBMBSXCB 


WX 


0032 


000000 




IBMBSIST 
SAMPLE 


WX 

LD 


0033 


000000 
000008 




SYSPINT 


SD 


0034 


000000 


000020 



> 
fl> 

3 



►* 



H 
O 

iQ 
H 

01 

& 

a 

uQ 

w 
x 

01 
3 
*1 



ro 
w 



PL/I OPTIMIZING COMPILER 



/***** pl/! SAMPLE PROGRAM- *****/ 
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o 

»o 
ft 

M- 

3 

H- 
N 
H« 
3 

U3 

o 
o 

3 
*0 
H" 
H 
rD 
h 



H 
O 

H 
0) 
3 
3 
<D 
H 



Oj 
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STATIC INTERNAL ST0RA3E MAP 


000000 


00000310 


PROGRAM/ DCON 


000004 


00000008 


PROGRAM 


ADCON 


000008 


00000078 


PROGRAM 


ADCON 


oooooc 


00000096 


PROGRAM 


ADCON 


000010 


000001C8 


PROGRAM 


ADCON 


000014 


0000021E 


PROGRAM 


ADCON 


000018 


00000448 


PROGRAM 


ADCON 


00001C 


0000049E 


PROGRAM 


ADCON 


000020 


000004A8 


PROGRAM 


ADCON 


000024 


00000788 


PROGRAM 


ADCON 


000028 


000007DE 


PROGRAM 


ADCON 


00002C 


000007F4 


PROGRAM 


ADCON 


000030 


0000085C 


PROGRAM 


ADCON 


000034 


0000085C 


PROGRAM 


ADCON 


000038 


0000085C 


PROGRAM 


ADCON 


00003C 


0000085C 


PROGRAM 


ADCON 


000040 


0000085C 


PROGRAM 


ADCON 


000044 


00000000 


A. .IELCGOA 


000048 


00000000 


A..IELCGOB 


00004C 


00000000 


A. . IBMBCCSA 


000050 


00000000 


A..IBMBCHPD 


000054 


00000000 


A. . IBMBCODE 


000058 


00000000 


A..IBMBCTHD 


00005C 


00000000 


A. .IBMBCDID 


000060 


00000000 


A..IBMBEOCA 


000064 


00000000 


A. .IBMBEOLA 


000068 


00000000 


A..IBMBJDTA 


00006C 


00000000 


A. .IBMBJTTA 


000070 


00000000 


A..IBMBOCLA 


000074 


00000000 


A. .IBMBOCLC 


000078 


00000000 


A..IBMBSEDB 


00007C 


00000000 


A. .IBMBSEOA 


000080 


00000000 


A. .IBMBSIOE 


000084 


00000000 


A. - IBMBSIOT 


000088 


00000000 


A..IBMBSLOA 


00008C 


00000000 


A. .IBKBSPLA 


000090 


00000000 


A. .IBMBSPOA 


000094 


00000000 


A. .IBKBCKDD 


000098 


58000017 


FED 




00009C 


2000 


DED..PDATE 


00009E 


54 00000814040680 
0808000000006800 
00680000 


FED 




0000B2 


58000009 


FED 




0000B6 


5400000814040680 
0808000008007400 
00740000 


FED 




0000CA 


0001 


CONSTANT 


OOOOCC 








0000D0 


0000000000060000 


LOCATOR. 


. PDATE 



0000D8 


000001DC00120000 


OOOOE0 


0000000000040000 


0000E8 


0000000000030000 


0000F0 


0000000000070000 


0000F8 


0000000000020000 


000100 


0000000000000000 


000108 


91E091E0 


00010C 


00000001 


000110 


00000065. 


000114 


46000000 


000118 


00000010 


00011C 


FFOOOOOO 


000120 


00000000 


000124 


80000000 


000128 


80000000 


00012C 


00000000 


000130 


00000000 


000134 


800001 OC 


000138 


00000000 


00013C 


00000000 


000140 


00000000 


000144 


80000000 


000148 


80000000 


00014C 


80000000 


000150 


00000000 


000154 


00000000 


000158 


00000000 


000 15C 


80000000 


000160 


00000000 


000164 


00000000 


000168 


00000000 


00016C 


00000000 


000170 


00000000 


000174 


80000000 


000178 


00000000 


0001 7C 


00000000 


000180 


00000000 


000184 


00000000 


000188 


00000000 


00018C 


00000000 


000190 


00000000 


000194 


80000000 


000198 


00000000 


00019C 


00000000 


0001A0 


00000000 


0001A4 


00000000 


0001A8 


80000000 


0001AC 


00000000 


0001B0 


00000000 


0001B4 


00000000 


0001B8 


80000000 


0001BC 


E2C1D4D7D3C540D7 



LOCATOR 

LOCATOR 

LOCATOR 

LOCATOR 

LOCATOR 

LOCATOR 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

A. . DCLCB 

A. .PDATE 

A. .TEMP 

A.. DCLCB 

A. . TEMP 

A.. CONST ANT 

A. .ENTRY PLIRETC 

A. .ENTRY PLIDOMP 

A. . TEMP 

A.. TEMP 

A. -FBVAR 

A. .TEMP 

A. -TEMP 

A.. TEMP 

A. .SIZE 

A. .RETCODE 

A. .ENTRY PLISRTA 

A. .TEMP 

A. .TEMP 

A. .SIZE 

A. -RETCODE 

A. -TEMP 

A.. ENTRY PLISRTB 

A.. ENTRY PLISRTC 

A.. TEMP 

A. .TEMP 

A.. SIZE 

A. .RETCODE 

A.. TEMP 

A. -TEMP 

A. .ENTRY PLISRTD 

A. . TEMP 

A.. TEMP 

A. -TEMP 

A. .RETCODE 

A.- ENTRY PLICKPT 

A. .ENTRY PLIREST 

A. .ENTRY PLICANC 

A. .RETCODE 

CONSTANT 



Static Internal Storage Map. This is a 
storage map of the static control 
section for the program. This control 
section is the third standard entry in 
the external symbol dictionary. 



© 



Six-digit offset (in hexa- 
decimal) . 



(2) Text (in hexadecimal) . 

(3) Comment indicating type of item to 
which the text refers. A comment 
appears only against the first 
line of the text for an item. 
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PASE 18 



> 

(D 

3 



*1 



o 

H 
01 

a 
p- 

3 

w 

a 

T1 



D9D6C7D9C1D47A40 

CttClE3C5«l07E<»0 
0001D3 6B40E3C9D4C5407E 

HO 
0001DC C5D5CMU0E2C1DUD7 

D3C5I»0D7D9D6C7D9 

C1D4 
0001EE E3C6C3C1 
0001F2 F1F2F7 
0001F5 D9C5E3C3D6CHC5 
0001FC C1D9C7F1 
000200 C1D9C7F2 
000204 D7E2 
000206 E2E8E2C3C8D2 
00020C 
000210 OC160000000001C8 



CONSTANT 
CONSTANT 



CONSTANT 
CONSTANT 
CONSTANT 
CONSTANT 
CONSTANT 
CONSTANT 
CONSTANT 

STATIC ONCB 



STATIC EXTERNAL CSECTS 



000000 FFFFFFFC41 201000 
02D70F0000000000 
011300140008E2E8 
E2D7D9C9D5E39040 



DCLCB 



to 

w 



to 



PL/I OPTIMIZING COMPILER 
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VARIABLE STORAGE MAP 
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* 
ft- 
H- 

3 

H- 
N 
H* 

3 

ia 

o 
o 

3 



IDENTIFIER 

BINVAR 

RETCODE 

FBVAR 

CVAR 

CKPT RETC 

PDATE 

PTIME 

OVAR 

SIZE 

PVAR 

ONCOONT 



LEVEL 



OPPSET 



(HEX) 



CLASS 



BLOCK 





192 


CO 


AUTO 


SAMPLE 




192 


CO 


AUTO 


SAMPLE 




196 


cn 


ADTO 


SAMPLE 




224 


E0 


AOTO 


SAMPLE 




200 


C8 


AUTO 


SAMPLE 




212 


D4 


AUTO 


SAMPLE 




218 


DA 


AUTO 


SAMPLE 


2 


168 


A8 


AUTO 


DUMMY 


2 


172 


AC 


AUTO 


DUMMY 




204 


CC 


AUTO 


SAMPLE 




208 


DO 


AUTO 


SAMPLE 



H 

H 
01 



a 
at 



PL/I OPTIMIZING COMPILER 
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PA3B 20 



•0 
H 

$ 
H 



9 

H 
X 

8) 

a 



TABLES OF OFFSETS AND STATEMENT NUMBERS 



WITHIN PROCEDDRE SAMPLE 



OFFSET (HEX) 





8E 


A4 


CO 


150 


158 


15C 


1711 


1AE 


STATEMENT NO. 


1 


5 


6 


7 


8 


9 


42 


43 


44 



WITHIN ON UNIT 



OFFSET (HEX) 





56 


60 


A8 


F0 


FA 


118 


13E 


180 


1C4 


206 


248 


266 


STATEMENT NO. 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 



WITHIN PROCEDURE DUMMY 



OFFSET (HEX) 





60 


70 


78 


7C 


D4 


140 


1AC 


22C 


298 


2FE 


308 


312 


32A 


STATEMENT NO. 


22 


24 


25 


26 


27 


28 


29 


30 


31 


32 


33 


34 


35 


41 



WITHIN PROCEDURE A 



OFFSET (HEX) 
STATEMENT NO. 




36 



56 
37 



> 

ft 

9 

d 



WITHIN PROCEDURE B 



OFFSET (HEX) 
STATEMENT NO. 




38 



68 
40 



to 
w 
w 



U) 



* 

ft 



N 
H- 

o 

3 

*P 
I* 

H 



ft) 






PL/I OPTIMIZING COMPILER 



OBJECT LISTING 

r? 



/***** PL/I SAMPLE PR03RAM. *****/ 
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* COMPILER GENERATED SUBROUTINE 



© 



000000 
000001 
000008 

oooooc 

000010 
00001ft 
00001A 
00001E 
000022 
000024 
000028 
00002C 
000030 
00003ft 
000038 
00003C 
000040 
OOOOftft 
000048 
Q0004A 
00004E 
000050 
000052 
000056 
00005A 
00005C 
000060 
00006ft 
000066 
00006A 
00006C 
000070 



50 EO 

58 FO 

91 10 

ft7 10 

96 Oft 

D2 03 

ft8 FO 

ftB FO 

07 B6 

96 ftO 

58 FO 

50 FO 

ftA FO 

ftA FO 

5ft FO 

55 FO 

ft7 20 

50 FO 

07 F6 

50 00 

18 71 

18 OF 

58 10 

58 FO 

05 EF 

50 00 

50 10 

18 17 

58 00 1 01C 

07 F6 

FFFFFFF8 



00C 

01ft 

Oil 

01ft 

002 

008 F OftC 

050 

002 

010 
OftC 
008 
002 
070 
06C 
00C 
OftA 
OftC 



1 01C 



OftC 
0ft8 



OftC 
008 



* END OF COMPILER GENERATED SUBROUTINE 



COMPILER GENERATED SUBROUTINE 



000000 


9ft 


FB 


C 


002 


00000ft 


91 


ftO 


1 


010 


000008 


ft7 


10 


7 


052 


oooooc 


58 


FO 


1 


01ft 


000010 


50 


70 


1 


01C 


00001ft 


58 


70 


1 


OOC 


000018 


ft8 


EO 


F 


050 


00001C 


ftB 


EO 


7 


002 


000020 


ftO 


EO 


F 


050 


00002ft 


58 


EO 


F 


OftC 


000028 


ftA 


EO 


7 


002 


00002C 


50 


EO 


F 


OftC 



IELCGOA 




ST 


1ft, 12(0,1) 


L 


15,20(0,1) 


TM 


17(1), X'10* 


BO 


♦ ♦8 


01 


2(12) ,X'04' 


MVC 


8(4,1), 76(15) 


LH 


15,80(0,15) 


SH 


15, 2(0, 1ft) 


BCR 


11,6 


01 


led^X'ftO' 


L 


15,76(0,13) 


ST 


15,8(0,1) 


AH 


15, 2(0, 1ft) 


AH 


15,112(0,7) 


N 


15,108(0,7) 


CL 


15,12(0,12) 


3H 


*+10 


ST 


15,76(0,13) 


BR 


6 


ST 


0,28(0,1) 


LR 


7,1 


LR 


0,15 


L 


1,76(0,13) 


L 


15,72(0,12) 


BALR 


1ft, 15 


ST 


0,76(0,13) 


ST 


1,8(0,7) 


LR 


1,7 


L 


0,28(0,1) 


BR 


6 


DC 


X'FFFFFFF8' 


DC 

nnTTMP 


AL2(7) 


IELCGOB 




NI 


2(12), X'PB' 


TM 


16(l),X , ftO* 


BO 


*+7ft 


L 


15,20(0,1) 


ST 


7,28(0,1) 


L 


7,12(0,1) 


LH 


1ft, 80(0,15) 


SH 


14,2(0,7) 


STH 


1ft, 80(0,15) 


L 


14,76(0,15) 


AH 


14,2(0,7) 


ST 


14,76(0,15) 



000030 


48 


EO 


1 


020 


00003ft 


41 


EO 


E 


001 


000038 


40 


EO 


1 


020 


0OO03C 


40 


EO 


F 


052 


000040 


91 


10 


1 


010 


000044 


07 


86 






000046 


58 


70 


1 


01C 


00004A 


58 


FO 


7 


068 


00004E 


05 


EF 






000050 


07 


F6 






000052 


58 


FO 


7 


06C 


000056 


05 


EF 






000058 


58 


EO 


1 


008 


00005C 


50 


EO 


D 


04C 


000060 


94 


BF 


1 


010 


000064 


07 


F6 






000066 


07 


00 






000068 










00006C 
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21 


LH 


14,32(0,1) 




LA 


14,1(0,14) 




STH 


14,32(0,1) 




STH 


1ft, 82(0, 15) 




TM 


16(1), X'10' 




BCR 


8,6 




L 


7,28(0,1) 




L 


15,10ft(0,7) 




BALR 


14,15 




BR 


6 




L 


15,108(0,7) 




BALR 


14,15 




L 


14,8(0,1) 




ST 


14,76(0,13) 




NI 


16(1), X'BF" 




BR 


6 




NOPR 







DC 


AL4 (0) 




DC 


AL4(0) 





* END OF COMPILER 3ENERATED SUBROUTINE 



DC 
DC 



* STATEMEN' 


" NUMBER 


000000 








000007 








* PROCEDURE 




* REAL 


ENTRY 




000008 


90 


EC 


D OOC 


OOOOOC 


47 


FO 


F 01ft 


000010 


00000000 


000014 


00000228 


000018 


00000000 


00001C 


58 


30 


F 010 


000020 


58 


10 


D OftC 


000024 


58 


00 


F OOC 


000028 


IE 


01 




00002A 


55 


00 


C OOC 


00002E 


47 


DO 


F 030 


000032 


58 


FO 


C 07ft 


000036 


05 


EF 




000038 


58 


EO 


D 0ft8 


00003C 


18 


FO 




00003E 


90 


EO 


1 048 


000042 


50 


DO 


1 004 


000046 


41 


Dl 


000 


00004A 


50 


50 


D 058 


00004E 


ftl 


60 


D 0A8 


000052 


50 


60 


D 070 


000056 


D7 


00 


D 0A8 



C SAMPLE* 
ALK6) 



SAMPLE 



D 0A8 



STM 


14,12,12(13) 


B 


*+16 


DC 


A(STMr. NO. TABLE) 


DC 


F'552' 


DC 


A( STATIC CSECT) 


L 


3,16(0,15) 


L 


1,76(0,13) 


L 


0,12(0,15) 


ALR 


0,1 


CL 


0,12(0,12) 


BNH 


*+10 


L 


15,116(0,12) 


BALR 


14,15 


L 


14,72(0,13) 


LR 


15,0 


STM 


14,0,72(1) 


ST 


13,4(0,1) 


LA 


13,0(1,0) 


ST 


5,88(0,13) 


LA 


6,168(0,13) 


ST 


6,112(0,13) 


XC 


168 (1,13), 168(13) 



Object listing. This is a listing of 
the machine instructions generated by 
the optimizing compiler from the PL/I 
source program. 



© 
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Machine instructions (in hexa- 
decimal) . 

Assembler-language form of the 
machine instructions. 



> 

3 
X 



H 

$ 
h 
0) 

3. 

3 
vO 

W 

01 

a 

M 



W 



PL/I OPTIMIZING COMPILER 



00005C 92 01 D 0A9 

000060 92 CO D 000 

000061 92 24 D 001 
000068 41 80 3 210 
00006C 50 80 D 05C 
000070 D2 03 D 054 3 108 
000076 05 20 

* PROLOGUE BASE 

000078 D2 07 D 0B0 3 0D0 



00007E 41 90 D 0D4 

000082 50 90 D 0B0 

000086 D2 07 D 0B8 3 

00008C 41 40 D ODA 

000090 50 40 D 0B8 

000094 05 20 

* PROCEDURE BASE 



/***** PL/I SAMPLE PROGRAM. *****/ 



* STATEMENT NUMBER 



000096 
00009A 
00009E 
0000A2 
0000A6 
0000AA 



41 40 D 0D4 
50 40 3 124 



96 80 
41 10 
58 FO 
05 EF 



124 
124 
068 



* STATEMENT NUMBER 7 
0000C8 41 40 D 200 
50 40 3 130 
92 20 D 211 
41 10 3 12C 
58 FO 3 080 
05 EF 

41 EO 3 098 
41 10 D 200 



OOOOCC 
0000D0 
0000D4 
0000D8 
0000DC 
0000DE 
0000E2 
0000E6 
OOOOEA 



50 10 D 1F8 
58 70 3 044 



ODO 



* STATEMENT NUMBER 6 

OOOOAC 41 40 D 200 

OOOOBO 50 40 3 128 

0000B4 96 80 3 128 

0000B8 41 10 3 128 

OOOOBC 58 FO 3 06C 

OOOOCO 05 EF 

0000C2 D2 05 D ODA D 200 



MVI 


169(13), X'Ol' 


0000EE 


05 


67 






MVI 


0(13), X'CO' 


0000F0 


58 


40 


D 


208 


MVI 


1(13),X'24« 


0000F4 


D2 


16 


4 


000 3 1BC 


LA 


8,528(0,3) 


0O00FA 


58 


70 


3 


048 


ST 


8,92(0,13) 


0000FE 


05 


67 






MVC 


84(4, 13), 264(3) 


000100 


41 


EO 


D 


OBO 


BALR 


2,0 


000104 


41 


FO 


3 


09C 






000108 


90 


EF 


1 


000 






00010C 


41 


EO 


3 


09E 


MVC 


LOCATOR. . PDATE ( 8 ) , 


000110 


50 


EO 


1 


00C 




208(3) 


000114 


58 


FO 


3 


078 


LA 


9, PDATE 


000118 


05 


EF 






ST 


9, LOCATOR.. PDATE 


00011A 


41 


EO 


3 


0B2 


MVC 


LOCATOR . . PTI ME ( 8 ) , 


00011E 


58 


10 


D 


1F8 




208(3) 


000122 


58 


70 


3 


044 


LA 


4, PTI ME 


000126 


05 


67 






ST 


4, LOCATOR.. PTIME 


000128 


58 


60 


D 


208 


BALR 


2,0 


00012C 


D2 


08 


6 


000 3 1D3 






000132 


58 


70 


3 


048 






000136 


05 


67 










000138 


41 


EO 


D 


0B8 






00013C 


50 


EO 


1 


000 






000140 


41 


EO 


3 


0B6 


LA 


4 , PDATE 


000144 


50 


EO 


1 


OOC 


ST 


4,292(0,3) 


000148 


58 


FO 


3 


078 


01 


292(3), X^O' 


00014C 


05 


EF 






LA 


1,292(0,3) 


00014E 


58 


10 


D 


1F8 


L 


15,A..IBMBJDTA 


000152 


58 


FO 


3 


084 


BALR 


14,15 


000156 


05 


EF 










* STATEMENr NUMBER 8 


LA 


4,512(0,13) 


000158 


58 


FO 


3 


110 


ST 


4,296(0,3) 


00015C 


50 


FO 


D 


OCO 


01 


296 (3), X' 80' 












LA 


1,296(0,3) 












L 


15,A..IBMBJTTA 


* STATEMENr NUMBER 9 


BALR 


14,15 


000160 


92 


OC 


D 


0A8 


MVC 


PTIME(6) ,512(13) 
















* STATEMENT NUMBER 42 






000164 


41 


40 


D 


OCO 


LA 


4,512(0,13) 


000168 


50 


40 


3 


124 


ST 


4,304(0,3) 


00016C 


96 


80 


3 


124 


MVI 


529(13), X'20' 


000170 


IB 


55 






LA 


1,300(0,3) 


000172 


41 


10 


3 


124 


L 


15,A..IBMBSIOE 


000176 


58 


FO 


3 


138 


BALR 


14,15 


00017A 


05 


EF 






LA 


14,152(0,3) 












LA 


1,512(0,13) 












ST 


1,504(0,13) 


* STATEMENr NUMBER 43 


L 


7,A..IELCGOA 


00017C 


41 


40 


D 


200 
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BALR 


6,7 


L 


4,520(0,13) 


MVC 


0(23,4), 444(3) 


L 


7,A..IELCGOB 


BALR 


6,7 


LA 


14,176(0,13) 


LA 


15, DED.. PDATE 


STM 


14,15,0(1) 


LA 


14,158(0,3) 


ST 


14,12(0,1) 


L 


15, A..IBMBSEDB 


BALR 


14,15 


LA 


14,178(0,3) 


L 


1,504(0,13) 


L 


7,A..IELCGOA 


BALR 


6,7 


L 


6,520(0,13) 


MVC 


0(9, 6), 467(3) 


L 


7,A..IELCGOB 


BALR 


6,7 


LA 


14,184(0,13) 


ST 


14,0(0,1) 


LA 


14,182(0,3) 


ST 


14,12(0,1) 


L 


15,A..IBMBSEDB 


BALR 


14,15 


L 


1,504(0,13) 


L 


15,A..IBMBSIOT 


BALR 


14,15 


L 


15,272(0,3) 


ST 


15, BICWAR. RETCODE 



MVI 168(13), X'OC 



LA 


4,BINVAR.RETCDDE 


ST 


4,292(0,3) 


01 


292 ( 3), X" 80* 


SR 


5,5 


LA 


1,292(0,3) 


L 


15,312(0,3) 


BALR 


14,15 


LA 


4,512(0,13) 



U 
00 


PL/I OPTIMIZING 


COMPIL 


8 


000180 


50 


40 


3 


130 


co 


00018a 


92 


40 


D 


211 


S 


000188 


41 


10 


3 


12C 




00018C 


58 


FO 


3 


080 


H 


000190 


05 


EF 






o 


000192 


41 


EO 


3 


0D8 


•0 
ft 


000196 


41 


FO 


3 


09C 


00019A 


41 


10 


D 


200 


s 


0001 9E 


50 


10 


D 


1F8 


N 


0001A2 


90 


EF 


1 


000 


3 


0001A6 


58 


FO 


3 


088 


5 


0001AA 


05 


EF 






O 


0001AC 


58 


10 


D 


1F8 




a 
•a 

H« 

H 
(D 
M 


0001B0 


58 


FO 


3 


084 


0001B4 


05 


EF 






* STATEMENT NUMBER 44 




0001B6 


18 


OD 






»d 


0001B8 


58 


DO 


D 


004 


h 


0001BC 


58 


EO 


D 


OOC 


5 


0001C0 


98 


2C 


D 


01C 


0) 


0001C4 


05 


IE 






fD 


* END PROCEDURE 




CO 


0001C6 


07 


07 








* STATEMENT NUMBER 9 
















* ON UNIT BLOCK 






0001C8 


90 


EC 


D 


OOC 




0001CC 


HI 


FO 


F 


014 




0001D0 


00000000 




0001D4 


OOOOOOEO 




0001D8 


00000000 




0001DC 


58 


30 


F 


010 




0001E0 


58 


10 


D 


04C 




0001E4 


58 


00 


F 


OOC 




0001E8 


IE 


01 








0001EA 


55 


00 


C 


OOC 




0001EE 


HI 


DO 


F 


30 




0001F2 


58 


FO 


C 


074 




0001F6 


05 


EF 








0001F8 


58 


EO 


D 


048 




0001FC 


18 


FO 








0001FE 


90 


EO 


1 


048 




000202 


50 


DO 


1 


004 




000206 


HI 


Dl 





000 




00020A 


50 


50 


D 


058 




00020E 


92 


8C 


D 


000 



/***** PL/I SAMPLE PR03RAM. *****/ 



PASE 23 



ST 


4,304(0,3) 


MVI 


529(13), X^O* 


LA 


1,300(0,3) 


L 


15,A..IBMBSI0E 


BALR 


14,15 


LA 


14,216(0,3) 


LA 


15,156(0,3) 


LA 


1,512(0,13) 


ST 


1,504(0,13) 


STM 


14,15,0(1) 


L 


15, A. .IBMBSLOA 


BALR 


14,15 


L 


1,504(0,13) 


L 


15,A..IBMBSI0T 


BALR 


14,15 


LR 


0,13 


L 


13,4(0,13) 


L 


14,12(0,13) 


LM 


2,12,28(13) 


BALR 


1,14 



NOPR 



STM 

B 

DC 

DC 

DC 

L 

L 

L 

ALR 

CL 

BNH 

L 

BALR 

L 

LR 

STM 

ST 

LA 

ST 

MVI 



14,12,12(13) 

20(0,15) 

A (STMT. NO. TABLE) 

F* 224* 

A (STATIC CSECT) 

3,16(0,15) 

1,76(0,13) 

0,12(0,15) 

0,1 

0,12(0,12) 

48(0,15) 

15,116(0,12) 

14,15 

14,72(0,13) 

15,0 

14,0,72(1) 

13,4(0,1) 

13,0(1,0) 

5,88(0,13) 

0(13), X*8C' 



000212 92 24 D 001 
000216 D2 03 D 054 3 108 
00021C 05 20 

* PROCEDURE BASE 



* STATEMENT NUMBER 10 
00021E IB 11 
000220 IB 55 
000222 58 FO 3 13C 
000226 05 EF 



* STATEMENT NUMBER 11 
000228 D2 03 D 0C0 3 1EE 
D2 07 D 0C4 3 0E0 



00022E 
000234 
000238 
00023C 
000240 
000244 
00024A 
000250 
000254 
000258 
00025C 
000260 
000264 
000266 
00026A 
00026E 



41 80 D 0C0 
50 80 D 0C4 



41 40 
50 40 
D2 02 
D2 07 



0C4 
140 
OCC 
0D0 



1F2 

0E8 



41 EO D OCC 
50 EO D 0D0 



41 40 
50 40 
96 80 
IB 55 
41 10 
58 FO 
05 EF 



ODO 
144 
144 

140 
13C 



* STATEMENT NUMBER 
000270 D2 03 D OCO 
D2 07 D 0C4 
41 80 D OCO 
50 80 D 0C4 
41 40 D 0C4 
50 40 3 140 
D2 06 D OCC 
D2 07 D 0D4 
41 80 D OCC 
50 80 D 0D4 



000276 
00027C 
000280 
000284 
000288 
00028C 
000292 
000298 
00029C 
0002A0 
0002A4 
0002A8 
0002AC 
0002AE 
0002B2 
0002B6 



12 

3 

3 



1EE 
OEO 



1F5 

OFO 



41 40 D 0D4 



50 40 
96 80 
IB 55 
41 10 
58 FO 
05 EF 



144 
144 

140 
13C 



MVI 1(13), X* 24' 
MVC 84(4, 13), 264(3) 
BALR 2,0 



SR 


1,1 


SR 


5,5 


L 


15,316(0,3) 


BALR 


14,15 


MVC 


192(4, 13), 494(3) 


MVC 


196(8, 13), 224(3) 


LA 


8,192(0,13) 


ST 


8,196(0,13) 


LA 


4,196(0,13) 


ST 


4,320(0,3) 


MVC 


204(3. 13), 498(3) 


MVC 


208(8, 13), 232(3) 


LA 


14,204(0,13) 


ST 


14,208(0,13) 


LA 


4,208(0,13) 


ST 


4,324(0,3) 


01 


324(3) ,X"80* 


SR 


5,5 


LA 


1,320(0,3) 


L 


15,316(0,3) 


BALR 


14,15 


MVC 


192(4, 13), 494 (-3) 


MVC 


196(8, 13), 224(3) 


LA 


8,192(0,13) 


ST 


8,196(0,13) 


LA 


4,196(0,13) 


ST 


4,320(0,3) 


MVC 


204(7, 13), 501(3) 


MVC 


212(8, 13), 240(3) 


LA 


8,204(0,13) 


ST 


8,212(0,13) 


LA 


4,212(0,13) 


ST 


4,324(0,3) 


01 


324(3), X'80 f 


SR 


5,5 


LA 


1,320(0,3) 


L 


15,316(0,3) 


BALR 


14,15 



PL/I OPTIMIZING COMPILER 



/***** PL/I SAMPLE PROSRAM. *****/ 



PA3E 24 



<b 
3 
Oi 
H« 



n 
$ 

H 

0) 

a 

3 

W 
X 

01 

a 



w 

SO 



* STATEMENT NUMBER 13 
0002B8 IB 11 
0002BA IB 55 
0002BC 58 F0 3 13C 
0002C0 05 EF 



* STATEMENT NUMBER 


0002C2 


58 


60 


D 058 


0002C6 


50 


60 


D 0B0 


0002CA 


41 


40 


6 0C4 


0002CE 


50 


40 


3 148 


0002D2 


96 


80 


3 148 


0002D6 


41 


10 


3 148 


0002DA 


58 


F0 


3 060 


0002DE 


05 


EF 





* STATEMENT NUMBER 15 

0002E0 58 40 D 048 

0002E4 4A 40 4 002 

0O02E8 CL.16 

0002E8 58 40 4 000 

0002EC 91 40 4 006 

0002F0 47 80 2 OCA 

0002F4 58 F0 4 010 

0002F8 48 70 3 OCA 

0002FC 40 70 6 0E0 

000300 D2 00 6 0E2 F 000 



* STATEMENT NUMBER 16 

000306 58 90 D 048 

00030A 4A 90 9 002 

00030E CL.17 

00030E 58 90 9 000 

000312 91 40 9 006 

000316 47 80 2 0F0 

00031A 58 40 9 018 

00031E 48 80 9 OlC 

000322 41 EO OFF 

000326 19 E8 

000328 47 DO 2 110 

00032C 18 E8 

00032E CL.18 

00032E 40 EO 6 0E0 

000332 4B EO 3 OCA 

000336 47 40 2 12A 

00033A 44 EO 2 124 

00033E 47 FO 2 12A 







000342 










CL. 


,20 


EQU 


* 






000342 


D2 


00 


6 


0E2 4 000 






MVC 


CVAR+2(1),0(4) 






000348 










cLi 


,19 


EQU 


* 


SR 


1.1 


000348 










CL. 


21 


E2U 


* 


SR 


5,5 




















L 


15,316(0,3) 




















BALR 


14,15 


* STATEMENT NUMBER 17 














000348 


41 


40 


D 


OCO 






LA 


4,192(0,13) 






00034C 


50 


40 


3 


14C 






ST 


4,332(0,3) 






000350 


96 


80 


3 


14C 






01 


332(3), X'80' 


L 


6,88(0,13) 


000354 


41 


10 


3 


14C 






LA 


1,332(0,3) 


ST 


6,176(0,13) 


000358 


58 


FO 


3 


064 






L 


15,A..IBMBEOLA 


LA 


4,BINVAR.FBVAR 


00035C 


05 


EF 










BALR 


14,15 


ST 


4,328(0,3) 


00035E 


58 


40 


D 


OCO 






L 


4,192(0,13) 


01 


328(3), X' 80* 


000362 


48 


80 


D 


OCH 






LH 


8,196(0,13) 


LA 


1,328(0,3) 


000366 


41 


EO 





OFF 






LA 


14,255(0,0) 


L 


15, A. . IBMBEOCA 


00O36A 


19 


E8 










CR 


14,8 


BALR 


14,15 


00036C 
000370 
000372 


47 
18 


DO 
E8 


2 


154 


CL. 


,22 


BNH 

LR 

EQU 


CL. 22 
14,8 

* 






000372 


40 


EO 


6 


0E0 






STH 


14, CVAR 


L 


4,72(0,13) 


000376 


4B 


EO 


3 


OCA 






SH 


14,202(0,3) 


AH 


4,2(0,4) 


00037A 


47 


40 


2 


16E 






3M 


CL.23 


EQU 


* 


00037E 


44 


EO 


2 


168 






EX 


14, CL. 24 


L 


4,0(0,4) 


000382 


47 


FO 


2 


16E 






B 


CL.25 


TM 


6(4),X'40' 


000386 










CL. 


.24 


EQU 


* 


BZ 


CL.16 


000386 


D2 


00 


6 


0E2 4 000 






MVC 


CVAR+2(1),0(4) 


L 


15,16(0,4) 


00038C 










CL, 


,23 


EQU 


* 


LH 


7,202(0,3) 


00038C 










CL. 


,25 


EQU 


* 


STH 


7 , CVAR 




















MVC 


CVAR+2(1),0(15) 
























* STATEMENT NUMBER 18 














00038C 


58 


40 


D 


048 






L 


4,72(0,13) 






000390 


4A 


40 


4 


002 






AH 


4,2(0,4) 


L 


9,72(0,13) 


000394 










CL. 


,26 


EQU 


* 


AH 


9,2(0,9) 


000394 


58 


40 


4 


000 






L 


4,0(0,4) 


EQU 


* 


000398 


91 


80 


4 


006 






TM 


6(4),X'80 f 


L 


9,0(0,9) 


00039C 


47 


80 


2 


176 






BZ 


CL.26 


TM 


6(9),X , 40' 


000 3A0 


58 


EO 


4 


008 






L 


14,8(0,4) 


BZ 


CL.17 


0003A4 


48 


90 


4 


OOC 






LH 


9,12(0,4) 


L 


4,24(0,9) 


0003A8 


41 


40 





OFF 






LA 


4,255(0,0) 


LH 


8,28(0,9) 


0003AC 


19 


49 










CR 


4,9 


LA 


14,255(0,0) 


000 3AE 


47 


DO 


2 


196 






BNH 


CL.27 


CR 


14,8 


0003B2 


18 


49 










LR 


4,9 


BNH 


CL.18 


0003B4 










CL. 


.27 


EQU 


* 


LR 


14,8 


0003B4 


40 


40 


6 


OEO 






STH 


4, CVAR 


EQU 


* 


0003B8 


4B 


40 


3 


OCA 






SH 


4,202(0,3) 


STH 


14, CVAR 


0003BC 


47 


40 


2 


1B0 






BM 


CL.28 


SH 


14,202(0,3) 


0003C0 


44 


40 


2 


1AA 






EX 


4,CL.29 


BM 


CL.19 


0003C4 


47 


FO 


2 


1B0 






B 


CL. 30 


EX 


14,CL.20 


0003C8 










CL. 


,29 


EQU 


* 


B 


CL.21 


000 3C8 


D2 


00 


6 


0E2 E 000 






MVC 


CVAR+2(1),0(14) 



K) 












J5 
O 


PL/I OPTIMIZING 


compil: 


8 


0003CE 












0003CE 




















X 












H 


* STATEMENT NUMBER 19 


8 


0003CE 


58 


40 


D 


048 


<+ 


0003D2 


4A 


40 


4 


002 




0003D6 










H- 


0003D6 


58 


40 


4 


000 


N 


0003DA 


91 


10 


4 


006 


3 


0003DE 


47 


80 


2 


1B8 


0003E2 


58 


E0 


4 


020 


O 


3 


0003E6 


48 


90 


4 


024 


0003EA 


41 


40 





OFF 


U 


0003EE 


19 


49 






fe* 


0003F0 


47 


DO 


2 


1D8 




0003F4 
0003F6 


18 


49 








0003F6 


40 


40 


6 


0E0 




0003FA 


4B 


40 


3 


OCA 


0003FE 


47 


40 


2 


1F2 


000402 


44 


40 


2 


1EC 


(U 


000406 


47 


F0 


2 


1F2 


3 
3 


00040A 










<T> 


00040A 


D2 


00 


6 


0E2 E 


H 


000110 










U 


000410 










<T> 












a 














* STATEMENT NUMBER 20 


0) 


000410 


78 


00 


6 


0D0 




000414 


7E 


00 


3 


114 




000418 


70 


00 


D 


OCO 




00041C 


91 


80 


D 


0C0 




000420 


48 


80 


D 


0C2 




000424 


47 


80 


2 


20C 




000428 


13 


88 








00042A 












0004 2A 


40 


80 


6 


0C4 




* STATEMENT NUMBER 21 




00042E 


18 


0D 








000430 


58 


DO 


D 


004 




000434 


58 


EO 


D 


OOC 




000438 


98 


2C 


D 


01C 




00043C 


05 


IE 







/***** PL/I SAMPLE PROGRAM. *****/ 
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000 



CL. 


28 


EQU 


* 


CL. 


,30 


EQU 


* 






L 


4,72(0,13) 






AH 


4,2(0,4) 


CL. 


,31 


EQU 


* 






L 


4,0(0,4) 






TM 


6(4),X'10' 






BZ 


CL.31 






L 


14,32(0,4) 






LH 


9,36(0,4) 






LA 


4,255(0,0) 






CR 


4,9 






BNH 


CL.32 






LR 


4,9 


CL, 


,32 


EQU 


* • 






STH 


4,CVAR 






SH 


4,202(0,3) 






BM 


CL.33 






EX 


4,CL.34 






B 


CL.35 


CL. 


,34 


EQU 


* 






MVC 


CVAR+2(1),0(1 


CL. 


,33 


EQU 


* 


CL. 


,35 


EQU 


* 






LE 


O.ONCOUNT 






AU 


0,276(0,3) 






STE 


0,192(0,13) 






TM 


192(13), X^O* 






LH 


8.194(0,13) 






BZ 


CL.36 






LCR 


8,8 


CL. 


.36 


EQU 


* 






STH 


8 , BINVAR. FBVA 






LR 


0,13 






L 


13,4(0,13) 






L 


14,12(0,13) 






LM 


2,12,28(13) 






BALR 


1,14 



* STATEMENT NUMBER 


000440 








000447 








* PROCEDURE 




* REAL 


ENTRY 




000448 


90 


EC 


D OOC 


00044C 


47 


FO 


F 014 


000450 


00000000 


000454 


0O0000E8 


000458 


00000000 


00045C 


58 


30 


F 010 


000460 


58 


10 


D 04C 


000464 


58 


00 


F OOC 


000468 


IE 


01 




00046A 


55 


00 


C OOC 


00046E 


47 


DC 


F 030 


000472 


58 


FO 


C 074 


000476 


05 


EF 




000478 


58 


EO 


D 048 


00047C 


18 


FO 




00047E 


90 


EO 


1 048 


000482 


50 


DO 


1 004 


000486 


41 


Dl 


000 


00048A 


50 


50 


D 058 


00048E 


92 


80 


D 000 


000492 


92 


24 


D 001 


000496 


D2 


03 


D 054 


00049C 


05 


20 




* PROLO 


SUE 


BASE 


00049E 


58 


60 


D 058 


0004A2 


50 


60 


D OBO 


0004A6 


05 


20 





22 



3 108 



* ON UNIT BLOCK END 
00043E 07 07 



* PROCEDURE BASE 



* STATEMENT NUMBER 24 
0004A8 58 70 6 OCC 
0004AC 92 00 7 000 
0004B0 58 EO 3 118 
0004B4 50 EO 7 004 



* STATEMENT NUMBER 25 
0004B8 58 70 3 11C 
0004BC 50 70 6 OCC 



DC 
DC 



C DUMMY* 
ALK5) 

DUMMY 



STM 


14,12,12(13) 


B 


*+16 


DC 


A(STMr. NO. TABLE) 


DC 


F*232' 


DC 


A (STATIC CSECD 


L 


3,16(0,15) 


L 


1,76(0,13) 


L 


0,12(0,15) 


ALR 


0,1 


CL 


0,12(0,12) 


BNH 


*+10 


L 


15,116(0,12) 


BALR 


14,15 


L 


14,72(0,13) 


LR 


15,0 


STM 


14,0,72(1) 


ST 


13,4(0,1) 


LA 


13,0(1,0) 


ST 


5,88(0,13) 


MVI 


0(13), X'80* 


MVI 


1(13), X'24 f 


MVC 


84(4,13), 264(3) 


BALR 


2,0 


L 


6,88(0,13) 


ST 


6,176(0,13) 


BALR 


2,0 



L 7 , PVAR 

MVI AVAR, X* 00' 

L 14,280(0,3) 

ST 14,AVAR+4 



L 
ST 



NOPR 7 



7,284(0,3) 
7, PVAR 



* STATEMENT NUMBER 26 



PL/I OPTIMIZING COMPILER 



0004C0 50 70 D 0A8 



/***** PL/I SAMPLE PROGRAM. *****/ 





* STATEMENT NUMBER 


27 




0004C4 


D2 


03 


D 


OCO 


3 


IPC 




0004CA 


D2 


07 


D 


0C4 


3 


OEO 




0004D0 


41 


80 


D 


OCO 








0004D4 


50 


80 


D 


0C4 








0004D8 


41 


40 


D 


0C4 








ooo4dc 


50 


40 


3 


150 








0004E0 


D2 


03 


D 


OCC 


3 


200 




0004E6 


D2 


07 


D 


0D0 


3 


OEO 




0004EC 


41 


40 


D 


OCC 








0004F0 


50 


40 


D 


0D0 








0004F4 


41 


40 


D 


ODO 








0004F8 


50 


40 


3 


154 








0004FC 


41 


40 


D 


OAC 








000500 


50 


40 


3 


158 








000504 


41 


40 


6 


OCO 








000508 


50 


40 


3 


15C 








00050C 


96 


80 


3 


15C 








000510 


IB 


55 












000512 


41 


10 


3 


150 








000516 


58 


FO 


3 


160 








00051A 


05 


EF 












* STATEMENT NUMBER 


26 


1 




00051C 


D2 


03 


D 


OCO 


3 


1FC 




000522 


D2 


07 


D 


0C4 


3 


OEO 


> 


000528 


41 


80 


D 


OCO 






*0 


00052C 


50 


80 


D 


0C4 






(D 


000530 


41 


40 


D 


0C4 






3 


000534 


50 


40 


3 


164 








000538 


D2 


03 


D 


OCC 


3 


200 




00053E 


D2 


07 


D 


ODO 


3 


OEO 


**1 


000544 


41 


EO 


D 


OCC 








000548 


50 


EO 


D 


ODO 






►0 


00054C 


41 


40 


D 


ODO 






H 


000550 


50 


40 


3 


168 









000554 


41 


40 


D 


OAC 






H 


000558 


50 


40 


3 


16C 






§ 


00055C 


41 


40 


6 


OCO 






3 


000560 


50 


40 


3 


170 






3 


000564 


50 


DO 


D 


ODC 






lO 


000568 


58 


FO 


3 


024 






W 


00056C 


50 


FO 


D 


0D8 






X 


000570 


41 


40 


D 


0D8 






13 


000574 


50 


40 


3 


174 






000578 


96 


80 


3 


174 






m 


00057C 


IB 


55 










to 


00057E 


41 


10 


3 


164 







ST 


7 f OVAR 


000582 
000586 


58 
05 


FO 
EF 


3 


178 




MVC 


192(4, 13), 508(3) 


* STATEMENT NUMBER 


29 


MVC 


196(8, 13), 224(3) 


000588 


D2 


03 


D 


OCO 


3 1FC 


LA 


8,192(0,13) 


00058E 


D2 


07 


b 


0C4 


3 OEO 


ST 


8,196(0,13) 


000594 


41 


80 


D 


OCO 




LA 


4,196(0,13) 


000598 


50 


80 


D 


0C4 




ST 


4,336(0,3) 


00059C 


41 


40 


D 


0C4 




MVC 


204(4, 13), 512(3) 


0005A0 


50 


40 


3 


164 




MVC 


208(8, 13), 224(3) 


0005A4 


D2 


03 


D 


OCC 


3 200 


LA 


4,204(0,13) 


0005AA 


D2 


07 


D 


ODO 


3 OEO 


ST 


4,208(0,13) 


0005B0 


41 


EO 


D 


OCC 




LA 


4,208(0,13) 


0005B4 


50 


EO 


D 


ODO 




ST 


4,340(0,3) 


0005B8 


41 


40 


D 


ODO 




LA 


4, SIZE 


0005BC 


50 


40 


3 


168 




ST 


4,344(0,3) 


0O05CO 


41 


40 


D 


OAC 




LA 


4,BINVAR.RETCODE 


0005C4 


50 


40 


3 


16C 




ST 


4,348(0,3) 


0005C8 


41 


40 


6 


OCO 




01 


348(3), X*80' 


000 5CC 


50 


40 


3 


170 




SR 


5,5 


0005D0 


50 


DO 


D 


ODC 




LA 


1,336(0,3) 


000 5D4 


58 


FO 


3 


02C 




L 


15,352(0,3) 


0005D8 


50 


FO 


D 


0D8 




BALR 


14,15 


0005DC 


41 


40 


D 


0D8 








0005E0 


50 


40 


3 


174 








0005E4 


96 


80 


3 


174 








0005E8 


IB 


55 








MVC 


192(4, 13), 508(3) 


0005EA 


41 


10 


3 


164 




MVC 


196(8, 13), 224(3) 


0005EE 


58 


FO 


3 


17C 




LA 


8,192(0,13) 


0005F2 


05 


EF 








ST 


8,196(0,13) 














LA 


4,196(0,13) 














ST 


4,356(0,3) 


* STATEMENT NUMBER 


30 


MVC 


204(4, 13), 512(3) 


0005F4 


D2 


03 


D 


OCO 


3 1FC 


MVC 


208(8, 13), 224(3) 


0005FA 


D2 


07 


D 


0C4 


3 OEO 


LA 


14,204(0,13) 


000600 


41 


80 


D 


OCO 




ST 


14,208(0,13) 


000604 


50 


80 


D 


0C4 




LA 


4,208(0,13) 


000608 


41 


40 


D 


0C4 




ST 


4,360(0,3) 


00060C 


50 


40 


3 


180 




LA 


4, SIZE 


000610 


D2 


03 


D 


OCC 


3 200 


ST 


4,364(0,3) 


000616 


D2 


07 


D 


ODO 


3 OEO 


LA 


4,BINVAR.RETCODE 


00061C 


41 


EO 


D 


OCC 




ST 


4,368(0,3) 


000620 


50 


EO 


D 


ODO 




ST 


13,220(0,13) 


000624 


41 


40 


D 


ODO 




L 


15,36(0,3) 


000628 


50 


40 


3 


184 




ST 


15,216(0,13) 


00062C 


41 


40 


D 


OAC 




LA 


4,216(0,13) 


000630 


50 


40 


3 


188 




ST 


4,372(0,3) 


000634 


41 


40 


6 


OCO 




01 


372(3), X'80' 


000638 


50 


40 


3 


18C 




SR 


5,5 


00063C 


50 


DO 


D 


ODC 




LA 


1,356(0,3) 


000640 


58 


FO 


3 


024 







PAGE 26 


L 


15,376(0,3) 


BALR 


14,15 


MVC 


192(4, 13), 508(3) 


MVC 


196(8, 13), 224(3) 


LA 


8,192(0,13) 


ST 


8,196(0,13) 


LA 


4,196(0,13) 


ST 


4,356(0,3) 


MVC 


204(4, 13), 512(3) 


MVC 


208(8, 13), 224(3) 


LA 


14,204(0,13) 


ST 


14,208(0,13) 


LA 


4,208(0,13) 


ST 


4,360(0,3) 


LA 


4, SIZE 


ST 


4,364(0,3) 


LA 


4,BINVAR.RETC0DE 


ST 


4,368(0,3) 


ST 


13,220(0,13) 


L 


15,44(0,3) 


ST 


15,216(0,13) 


LA 


4,216(0,13) 


ST 


4,372(0,3) 


01 


372(3) ^'SO* 


SR 


5,5 


LA 


1,356(0,3) 


L 


15,380(0,3) 


BALR 


14,15 


MVC 


192(4, 13), 508(3) 


MVC 


196(8, 13), 224(3) 


LA 


8,192(0,13) 


ST 


8,196(0,13) 


LA 


4,196(0,13) 


ST 


4,384(0,3) 


MVC 


204(4, 13), 512(3) 


MVC 


208(8, 13), 224(3) 


LA 


14,204(0,13) 


ST. 


14,208(0,13) 


LA 


4,208(0,13) 


ST 


4,388(0,3) 


LA 


4, SIZE 


ST 


4,392(0,3) 


LA 


4,BINVAR.RETC0DE 


ST 


4,396(0,3) 


ST 


13,220(0,13) 


L 


15,36(0,3) 



to 


PL/I OPTIMIZING 


COMPILER 


/***** 


PL/ I SAMPLE PROGRAM 


. *****/ 








PAGE 27 


8 


000641 


50 


F0 


D 


0D8 






ST 


15,216(0,13) 


000706 


50 


EO D ODO 


ST 


14,208(0,13) 


000648 


41 


40 


D 


0D8 






LA 


4,216(0,13) 


00070A 


41 


40 D ODO 


LA 


4,208(0,13) 


5 


00064C 


50 


40 


3 


190 






ST 


4,400(0,3) 


00070E 


50 


40 3 1A0 


ST 


4,416(0,3) 


000650 


50 


DO 


D 


0E4 






ST 


13,228(0,13) 


000712 


D2 


01 D ODA 3 204 


MVC 


218(2, 13), 516(3) 


H 


000654 


58 


F0 


3 


02C 






L 


15,44(0,3) 


000718 


D2 


07 D ODC 3 0F8 


MVC 


220(8, 13), 248(3) 


o 


000658 


50 


F0 


D 


0E0 






ST 


15,224(0,13) 


00071E 


41 


80 D ODA 


LA 


8,218(0,13) 


■» 


00065C 


41 


40 


D 


0E0 






LA 


4,224(0,13) 


000722 


50 


80 D ODC 


ST 


8,220(0,13) 


H« 


000660 


50 


40 


3 


194 






ST 


4,404(0,3) 


000726 


41 


40 D ODC 


LA 


4,220(0,13) 


3 


000664 


96 


80 


3 


194 






01 


404(3), X'80* 


00072A 


50 


40 3 1A4 


ST 


4,420(0,3) 


N 


000668 


IB 


55 










SR 


5,5 


00072E 


41 


40 6 0C8 


LA 


4,CKPT RETC 


3 


00066A 


41 


10 


3 


180 






LA 


1,384(0,3) 


000732 


50 


40 3 1A8 


ST 


4,424(0,3) 


03 


00066E 


58 


F0 


3 


198 






L 


15,408(0,3) 


000736 


96 


80 3 1A8 


01 


424(3) ,X'80' 


O 


000672 


05 


EF 










BALR 


14,15 


00073A 


IB 


55 


SR 


5,5 


§ 




















00073C 


41 


10 3 19C 


LA 


1,412(0,3) 


►0 




















000740 


58 


FO 3 1AC 


L 


15,428(0,3) 


H 


* STATEMENT NUMBER 


31 








000744 


05 


EF 


BALR 


14,15 


(t> 


000674 


D2 


03 


D 


OCO 


3 


1FC 


MVC 


192(4, 13), 508(3) 












•"1 

•• 


00067A 


D2 


07 


D 


0C4 


3 


OEO 


MVC 


196(8, 13), 224(3) 














000680 


41 


80 


D 


OCO 






LA 


8,192(0,13) 


* STATEMENT NUMBER 33 






»T3 


000684 


50 


80 


D 


0C4 






ST 


8,196(0,13) 


000746 


IB 


11 


SR 


1.1 


8 


000688 


41 


40 


D 


0C4 






LA 


4,196(0,13) 


000748 


IB 


55 


SR 


5,5 


00068C 


50 


40 


3 


19C 






ST 


4,412(0,3) 


00074A 


58 


FO 3 1B0 


L 


15,432(0,3) 


h 


000690 


D2 


03 


D 


OCC 


3 


200 


MVC 


204(4, 13), 512(3) 


00074E 


05 


EF 


BALR 


14,15 


i 


000696 


D2 


07 


D 


0D0 


3 


OEO 


MVC 


208(8, 13), 224(3) 












fl> 


00069C 


41 


E0 


D 


OCC 






LA 


14,204(0,13) 












H 


0006A0 


50 


E0 


D 


0D0 






ST 


14,208(0,13) 


* STATEMENT NUMBER 34 






CD 


0006A4 


41 


40 


D 


0D0 






LA 


4,208(0,13) 


000750 


IB 


11 


SR 


1.1 


d 


0006A8 


50 


40 


3 


1A0 






ST 


4,416(0,3) 


000752 


IB 


55 


SR 


5,5 


0006AC 


D2 


01 


D 


ODA 


3 


204 


MVC 


218(2, 13), 516(3) 


000754 


58 


FO 3 1B4 


L 


15,436(0,3) 




0006B2 


D2 


07 


D 


ODC 


3 


0F8 


MVC 


220(8, 13),248(3) 


000758 


05 


EF 


BALR 


14,15 


A 


0006B8 
0006BC 


41 
50 


80 
80 


D 
D 


ODA 
ODC 






LA 
ST 


8,218(0,13) 
8,220(0,13) 














0006C0 


41 


40 


D 


ODC 






LA 


4,220(0,13) 


* STATEMENr NUMBER 35 








0006C4 


50 


40 


3 


1A4 






ST 


4,420(0,3) 


00075A 


41 


40 6 OCO 


LA 


4, BINVAR. RETCODE 




0006C8 


41 


40 


6 


OCO 






LA 


4 , BINVAR. RETCODE 


00075E 


50 


40 3 1B8 


ST 


4,440(0,3) 




0006CC 


50 


40 


3 


1A8 






ST 


4,424(0,3) 


000762 


96 


80 3 1B8 


01 


440(3), X'80" 




0006D0 


96 


80 


3 


1A8 






01 


424(3), X*80* 


000766 


IB 


55 


SR 


5,5 




0006D4 


IB 


55 










SR 


5,5 


000768 


41 


10 3 1B8 


LA 


1,440(0,3) 




0006D6 


41 


10 


3 


19C 






LA 


1,412(0,3) 


00076C 


58 


FO 3 138 


L 


15,312(0,3) 




0006DA 


58 


F0 


3 


1AC 






L 


15,428(0,3) 


000770 


05 


EF 


BALR 


14,15 




0006OE 


05 


EF 










BALR 


14,15 
































* STATEMENT NUMBER 41 








* STATEMENT NUMBER 


32 






000772 


18 


OD 


LR 


0,13 




0006E0 


D2 


05 


D 


0C2 


3 


206 


MVC 


194(6, 13), 518 (3) 


000774 


58 


DO D 004 


L 


13,4(0,13) 




0006E6 


D2 


07 


D 


0C8 


3 


ODO 


MVC 


200(8, 13), 208(3) 


000778 


58 


EO D OOC 


L 


14,12(0,13) 




0006EC 


41 


E0 


D 


0C2 






LA 


14,194(0,13) 


00077C 


98 


2C D 01C 


LM 


2,12,28(13) 




0006P0 


50 


EO 


D 


0C8 






ST 


14,200(0,13) 


000780 


05 


IE 


BALR 


1,14 




0006F4 


41 


40 


D 


0C8 






LA 


4,200(0,13) 














0006F8 


50 


40 


3 


19C 






ST 


4,412(0,3) 


* END PROCEDURE 








0006FC 


D2 


07 


D 


ODO 


3 


100 


MVC 


208(8, 13), 256(3) 


000782 


07 


07 


NOPR 


7 




000702 


41 


EO 


D 


ODO 






LA 


14,208(0,13) 













PL/I OPTIMIZING COMPILER 





* STATEMENT NUMBER 36 




000781 










000787 










* PROCEDURE 






* REAL 


ENTRY 






000788 


90 


EC D 


OOC 




00078C 


17 


F0 F 


Oil 




000790 


00000000 




000791 


000000B8 




000798 


oooooooc 


) 




00079C 


58 


30 F 


010 




0007A0 


58 


10 D 


01C 




0007A1 


58 


00 F 


OOC 




0007A8 


IE 


01 






0007AA 


55 


00 C 


OOC 




0007AE 


17 


DO F 


30 




0007B2 


58 


F0 C 


071 




0007B6 


05 


EF 






0007B8 


58 


E0 D 


018 




0007BC 


18 


FO 






0007BE 


90 


EO 1 


018 




0007C2 


50 


DO 1 


001 




0007C6 


11 


Dl 


000 




0007CA 


50 


50 D 


058 




0007CE 


92 


80 D 


000 




0007D2 


92 


21 D 


001 




0007D6 


D2 


03 D 


051 3 


> 


0007DC 


05 


20 




tJ 










•0 


* PROCEDURE BASE 












H« 










X 


* STATEMENT NUMBER 37 


Hj 


0007DE 


18 


OD 




M 


0007E0 


58 


DO D 


001 


•0 


0007E1 


58 


EO D 


OOC 


0007E8 


98 


2C D 


01C 



H 


0007EC 


05 


IE 












B 


* END PROCEDURE 




| 


0007EE 


07 


07 




5* 










tO 










H 


* STATEMENT NUMBER 38 


X 


0007F0 








§ 


0007F3 








H 










* PROCEDURE 




K) 










* 










W 











108 



***** 


PL/ I SAMPLE PROGRA^ 


!. *****/ 












PAGE 28 






* REAL 


ENTRY 














0007F1 


90 


EC 


D 


OOC 


STM 


11*12,12(13) 


DC 


C A' 


0007F8 


17 


FO 


F 


Oil 


B 


*+16 


DC 


ALl(l) 


0007FC 


00000000 


DC 


A(STMr. NO. TABLE) 






000800 


000000CE 


\ 


DC 


F^OO' 




A 


000801 


00000000 


DC 


A(STATIC CSECD 






000808 


58 


30 


F 


010 


L 


3,16(0,15) 






00080C 


58 


10 


D 


01C 


L 


1,76(0,13) 


STM 


11,12,12(13) 


000810 


58 


00 


F 


OOC 


L 


0,12(0,15) 


B 


*+16 


000811 


IE 


01 






ALR 


0,1 


DC 


A (STMT. NO. TABLE) 


000816 


55 


00 


C 


OOC 


CL 


0,12(0,12) 


DC 


F*184' a 


00081A 


17 


DO 


F 


030 


BNH 


*+10 


DC 


A (STATIC CSECT) 


00081E 


58 


FO 


C 


071 


L 


15,116(0,12) 


L 


3,16(0,15) 


000822 


05 


EF 






BALR 


11,15 


L 


1,76(0,13) 


000821 


58 


EO 


D 


018 


L 


11,72(0,13) 


L 


0,12(0,15) 


000828 


18 


FO 






LR 


15,0 


ALR 


0,1 


00082A 


90 


EO 


1 


018 


STM 


11,0,72(1) 


CL 


0,12(0,12) 


00082E 


50 


DO 


1 


001 


ST 


13,1(0,1) 


BNH 


*+10 


000832 


11 


Dl 





000 


LA 


13,0(1,0) 


L 


15,116(0,12) 


000836 


50 


50 


D 


058 


ST 


5,88(0,13) 


BALR 


11,15 


0008 3A 


92 


80 


D 


000 


MVI 


0(13),X'80' 


L 


11,72(0,13) 


00083E 


92 


21 


D 


001 


MVI 


1(13),X"21« 


LR 


15,0 


Q00812 


D2 


03 


D 


051 3 108 


MVC 


81(1,13) ,261(3) 


STM 


11,0,72(1) 


000818 


58 


10 


D 


001 


L 


1,1(0,13) 


ST 


13,1(0,1) 


0008 1C 


58 


10 


1 


018 


L 


1,21(0,1) 


LA 


13,0(1,0) 


000850 


D2 


03 


D 


0B0 1 000 


MVC 


176(1, 13), 0(1) 


ST 


5,88(0,13) 


000856 


92 


00 


D 


0B0 


MVI 


176(13), X'OO" 


MVI 


0(13), X^O" 


00085A 


05 


20 






BALR 


2,0 


MVI 


1(13), X'21' 
















MVC 


81(1, 13), 261(3) 


* PROCEDURE BASE 






BALR 


2,0 




















* STATEMENT NUMBER 10 










00085C 


18 


OD 






LR 


0,13 






00085E 


58 


DO 


D 


001 


L 


13,1(0,13) 






000862 


58 


EO 


D 


OOC 


L 


11,12(0,13) 


LR 


0,13 


000866 


98 


2C 


D 


01C 


LM 


2,12,28(13) 


L 


13,1(0,13) 


00086A 


05 


IE 






BALR 


1.11 


L 


11,12(0,13) 
















LM 


2,12,28(13) 


* END PROCEDURE 








BALR 


lfll 




















* END PROGRAM 










NOPR 


7 
















DC 


C B* 
















DC 


ALK1) 

















PL/I OPTIMIZING COMPILER 



/***** PL/I SAMPLE PROGRAM. *****/ 



PAGE 29 



8 

H 
ft 



COMPILER DIAGNOSTIC MESSAGES 

O © O 

ERROR ID L STMT MESSAGE DESCRIPTION 



SEVERE AND ERROR DIAGNOSTIC MESSAGES 



IEL0413I E 23 



DECLARATION OF INTERNAL ENTRY NOT ALLOWED. 



DECLARATION OF 'A* I3NORED. 



i 
v. 

H 
H 






WARNING DIAGNOSTIC MESSAGES 



IEL0892I W 6 TARGET STRING SHORTER THAN SOURCE. RESULT TRUNCATED ON ASSIGNMENT. 

IEL0518I W 20 'ONCOUNT' IS THE NAME OF A BDILTIN FUNCTION BUT ITS IMPLICIT DECLARATION DOES HOT IMPLY 
' BUILTIN' . 

IEL0916I tf 22 ITEM(S) 'SIZE* MAY BE UNINITIALIZED WHEN USED IN THIS BLOCK. 



COMPILER INFORMATORY MESSAGES 



IEL0511I I 



1, 9, 22, 36, 38 



'ORDER* OPTION APPLIES TO THIS BLOCK. 



OPTIMIZATION MAY BE INHIBITED. 



c 



END OF COMPILER DIAGNOSTIC MESSAGES 



© 

COMPILE TIME 



0.12 MINS 



© 



SPILL FILE: 



2 RECORDS, SIZE 3191 



Diagnostic messages and an end of 
compile step message generated by the 
compiler. All diagnostic messages 
generated by the optimizing compiler 
are documented in the publication OS 
Optimizing Compiler: Messages . 

(?) "ERROR ID" This identifies the 
message as originating from the 
optimizing compiler (IEL) , and 
gives the message number. 



© 



2) "L" This is the severity level 
of the message. 



© 



3") "STMT" This gives the number of 
the statement in which the error 
occurred. 



© 



U) Compile time in minutes. This 
time includes the preprocessor. 



© 



5) This gives the number of records 
"spilled" into auxiliary storage 
and the size in bytes of the 
spill file. 



F88-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF.LIST S7\ 

DEFAULT OPTION(S) USED - SIZE=(102400, 57344) \ls 



> 

9 

a 



o 

H 



5" 

M 
X 






© 



CONTROL SECTION 

NAME ORIGIN LENGTH 



(D CROSS REFERENCE TABLE 

ENTRY 

NAME LOCATION NAME LOCATION 



NAME LOCATION NAME LOCATION 



PLISTART 



00 



44 



PLIMAIN 

STSPINT 

♦SAMPLE2 

IELCGOA 

IELCGOB 

•SAMPLE1 


48 

50 

70 

388 

400 

470 


8 
20 

314 
72 
70 

86C 


IBMBKCPl* 


CEO 


232 


IBMBKST1* 


F18 


6A0 


IBMBPIR1* 


15B8 


2F0 


IBMBCCS1* 


18A8 


180 


IBMBCH01* 


1A28 


ISO 


IBMBCOOl* 


1C08 


448 


IBMBCT01* 


2050 


29C 


IBMBCOOl* 


22P0 


308 


IBMBEOC1* 


25F8 


E6 


IBMBKDM1* 


26E0 


F8 


IBMBPRC1* 


27D8 


48 


IBMBSED1* 


2820 


488 


IBMBSIOl* 


2CA8 


260 


IBMBCK01* 


2P08 


176 


IBMBEOL1* 


3080 


AO 



PLICALLA 



SAMPLE 

IBMBKCPA 

IBMBKSTA 

IBMBPIRA 

IBMBCCSA 

IBMBCHXE 
IBMBCHXY 
IBMBCHFD 

IBMBCODE 

IBMBCTHD 
IBMBCTHE 

IBMBCOIX 
IBMBCUIF 

IBMBEOCA 

IBMBKDMA 

IBMBPRCA 

IBMBSEDA 

IBMBSIOA 
IBMBSIOE 

IBMBCKDP 

IBMBEOLA 



6 PLICALLB 



478 

CEO 

F18 

15DA 

18A8 

1A28 
1A38 
1A48 

1C08 

2050 
2070 

22F0 
2310 

25F8 

26E0 

27D8 

2820 

2CA8 
2CB0 

2F08 

3080 



IBMBKCPB 
IBMBKSTB 
IBMBPIRB 

IBMBCHFE 
IBMBCHFY 
IBMBCBXD 

IBMBCOZE 

IBMBCTHX 

IBMBCOID 



CE2 

F1A 

15DC 

1A28 
1A38 
1A48 

1C08 

2058 

22F8 



IBMBKCPC 
IBMBKSTC 
IB.HBPIRC 

IBMBCHXP 
IBMBCHFH 
IBMBCHXP 

IBMBCOOP 

IBMBCTHP 

IBMBCDIP 



IBMBSEDB 



IBMBSIOB 
IBMBSIOT 



IBMBCKZP 



2820 



2CAA 
2E66 



2F08 



IBMBSIOC 



IBHBCKDD 



CE4 

F1C 

15DE 



IBMBKSTD 



1A30 IBMBCHFP 
1A40 IBMBCHXH 
1A50 



1C08 
2060 

2300 



IBMBCTHP 



IBMBC0IE 



FIE 



1A30 
1A40 



2068 



2308 



First page of the linkage editor 
listing. 

(T) Statement identifying the version 
and level of the linkage editor 
and giving the options as 
specified in the PARM parameter of 
the EXEC statement that invokes 
the cataloged procedure. 

(2) Cross reference table. This table 
consists of a module map and the 
cross-reference table. 

(3) The module map shows each control 
section and its associated entry 
points, if any, listed across the 
page. An asterisk after the name 
means that these are library 
subroutines obtained by automatic 
library call. 

(4) The cross-reference table gives 
all the locations in a control 
section at which a symbol is 
referenced . ^UNRESOLVED (W) 
identifies a wak external 
reference that has not been 
resolved. 



NAME 
IBMBERR1* 



ORIGIN LENGTH 
3120 6C0 



CO 


IBMBJDT1* 


37E0 


8C 




2 








IBMBJDTA 


? 


IBMBJTT1 * 


3870 


68 




H 








IBMBJTTA 


o 


IBMBOCL1* 


3808 


10C 




ft 








IBMBOCLA 


IBMBSEOl* 


39E8 


E8 




3 








IBMBSEOA 


N 


IBMBSLOl* 


3 ADO 


6E0 




3 








IBMBSLOA 


IBMBSPL1* 


41B0 


2D0 




o 








IBMBSPLA 





IBMBSPOl* 


4480 


120 




3 
*0 








IBMBSPOA 


p. 
H 


IBMBCGT1* 


4 SAO 


88 










IBMBCGTA 


H 


IBMBEEF1* 


4628 


149 


IBMBEEFA 


•0 


IBMBEER1* 


4778 


4 




H 








IBMBEERA 





IBMBSCV1* 


4780 


240 












IBMBSCVA 




LOCATION 


REFERS 


TO SYMBOL IN 


CONTROL SECTION 


(0 


10 




PLIMAIN 


PLIMAIN 




18 




PLIFLOW 


$ UNRESOLVED (W) 


a. 


2C 




PLICOUNT 


$UNRESOLVED<») 


38 




IBMBPIRA 


IBMBPIR1 




40 




IBMBPIRC 


IBMBPIR1 




74 




♦SAMPLEl 


♦SAMPLEl 




7C 




♦SAMPLEl 


♦SAMPLEl 




84 




♦SAMPLEl 


♦SAMPLEl 




8C 




♦SAMPLEl 


♦SAMPLEl 




94 




♦SAMPLEl 


♦SAMPLEl 




9C 




♦SAMPLEl 


♦SAMPLEl 




A4 




♦SAMPLEl 


♦SAMPLEl 




AC 




♦SAMPLEl 


♦SAMPLEl 




B4 




IELCGOA 


IELCGOA 




BC 




IBMBCCSA 


IBMBCCS1 




C4 




IBMBCODE 


IBMBCO01 




CC 




IBMBCUID 


IBMBCO01 




D4 




IBMBEOLA 


IBMBEOL1 




DC 




IBMBJTTA 


IBMBJTT1 




E4 




IBMBOCLC 


IBMBOCL1 




EC 




IBMBSEOA 


IBMBSEOl 




F4 




IBMBSIOT 


IBMBSIOl 




FC 




IBMBSPLA 


IBMBSPL1 




104 




IBMBCKDD 


IBMBCK01 



NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 

JMBERRA 3120 IBMBERRB 3162 IBMBERRC 3734 
37E0 
3870 
38D8 
39E8 
3 ADO 
41B0 
4480 
45A0 
4628 
4778 
4780 

LOCATION REFERS TO SYMBOL IN CONTROL SECTION 



IBMBOCLB 38DA IBMBOCLC 38DC IBMBOCLD 38DE 

IBMBSLOB 3AD2 

IBMBSPLB 41B2 IBMBSPLC 41B4 



14 
1C 
30 
3C 
48 
78 
80 
88 
90 
98 
A0 
A8 
B0 
B8 
CO 
C8 
DO 
D8 
EO 
E8 
FO 
F8 
100 
190 



SYSPINT 

PLITABS 

PLIXOPT 

IBMBPIRB 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

IELCGOB 

IBMBCHFD 

IBMBCTHD 

IBMBEOCA 

IBMBJDTA 

IBMBOCLA 

IBMBSEDB 

IBMBSIOE 

IBMBSLOA 

IBMBSPOA 

SYS PI NT 



SYS PI NT 
$UNRESOLVED(H) 
$ UNRESOLVED (W) 

IBMBPIR1 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

♦SAMPLEl 

IELCGOB 

IBMBCH01 

IBMBCT01 

IBMBEOCl 

IBMBJDT1 

IBMBOCL1 

IBMBSED1 

IBMBSIOl 

IBMBSLOl 

IBMBSPOl 

SYS PI NT 



> 

ft) 
3 
Qi 
H« 
X 



O 



3 
3 

W 
0) 



LOCATION 


REFERS TO SYMBOL IN 


CONTROL SECTION 


LOCATION 


19C 


SYSPINT 


SYSPINT 


1A8 


1AC 


IBMBKDMA 


IBMBKDM1 


1D0 


1E8 


IBMBKSTB 


IBMBKST1 


1EC 


208 


IBMBKSTD 


IBMBKST1 


21C 


220 


IBMBKCPB 


IBMBKCP1 


224 


28a 


♦SAMPLE1 


♦SAMPLEl 


28C 


2C0 


♦SAMPLEl 


♦SAMPLEl 


304 


34C 


♦SAMPLEl 


♦SAMPLEl 


364 


468 


IBMBSIST 


$UNRESOLVED(W) 


46C 


480 


♦SAMPLE2 


♦SAMPLE2 


488 


640 


*SAMPLE2 


♦SAMPLE2 


648 


8C0 


♦SAMPLE2 


♦SAMPLE2 


8C8 


COO 


♦SAMPLE 2 


♦SAMPLE2 


C08 


C6C 


♦SAMPLE2 


♦SAMPLE2 


C74 


15B0 


IBMCKEXA 


$UNRESOLVED(W) 


15B4 


1840 


IBMBJWTA 


$UNRESOLVED(W) 


1844 


1848 


IBMBTOCB 


$UNRESOLVED(W) 


184C 


1800 


IBMBOCLB 


IBMBOCL1 


1814 


1830 


IBMBOCLD 


IBMBOCL1 


1838 


183C 


IBMBPGOA 


$UNRESOLVED(W) 


1850 


1868 


IBMBERRC 


IBMBERR1 


182C 


1834 


IBMBERRA 


IBMBERR1 


1870 


195C 


IBMBCHXD 


IBMBCH01 


1960 


196C 


IBMBCHXP 


IBMBCH01 


1970 


19711 


IBMBCHXE 


IBMBCH01 


199C 


19 AC 


IBMBCKDP 


IBMBCK01 


19 DC 


19E8 


IBMBCHFH 


IBMBCH01 


19EC 


19F0 


IBMBCHFY 


IBMBCH01 


19F4 


1998 


IBMBCEDX 


$UNRESOLVED(W) 


19A0 


19D8 


IBMBCEFX 


$UNRESOLVED(W) 


1958 


19E0 


IBMBCYFF 


$UNRESOLVED(W) 


1A18 


1A1C 


IBMBCMPD 


$UNRESOLVED(W> 


1A20 


1A0C 


IBMBCUIX 


IBMBCU01 


1A14 


19CC 


IBMBCTHX 


IBMBCT01 


19D0 


19D4 


IBMBCTHF 


IBMBCT01 


19B4 


19B0 


IBMBCVDY 


$UNRESOLVED(W) 


197C 


1984 


IBMBCRXB 


$UNRESOLVED<W) 


19FC 


1A04 


IBMBCRXB 


$UNRESOLVED(W) 


19A8 


1990 


IBMBCGZA 


$UNRESOLVED(W) 


1994 


1978 


IBMBCACA 


$UNRESOLVED(W) 


1980 


1988 


IBMBCACA 


$UNRESOLVED(W) 


19B8 


19C0 


IBMBCACA 


$UNRESOLVED(W) 


19C8 


19F8 


IBMBCACA 


$UNRESOLVED(W) 


1A00 


1A08 


IBMBCACA 


$UNRESOLVED(W) 


1A24 


1968 


IBMBCHXH 


IBMBCH01 


19BC 


19C4 


IBMBCEDB 


$UNRESOLVED(W) 


198C 


1A2C 


IBMBCOZE 


IBMBCO01 


1A34 


1A3C 


IBMBCVZY 


$UNRESOLVED(W) 


1A44 


1A4C 


IBMBCKZD 


IBMBCK01 


1BEC 


2054 


IBMBCKZD 


IBMBCK01 


2074 


2064 


IBMBCEZF 


$UNRESOLVED(W) 


206C 


205C 


IBMBCEZX 


$UNRESOLVED(W) 


22E8 



REFERS TO SYMBOL IN CONTROL SECTION 



IBMBPRCA 
IBMBKSTA 
IBMBKSTC 
IBMBKCPA 
IBMBKCPC 
♦SAMPLEl 
*SAMPLE1 
*S AMPLE 1 
IBMBSEOA 
*SAMPLE2 
♦SAMPLE 2 
♦SAMPLE2 
♦SAMPLE 2 
♦SAMPLE2 
IBMCKEXB 
IBMBTOCA 
IBMBTPRA 
IBMBOCLB 
IBMBERRB 
IBMBPQDA 
IBMBOCLA 
IBMBEERA 
IBMBCHXF 
IBMBCHXY 
IBMBCKDD 
IBMBCHFD 
IBMBCHFP 
IBMBCHFE 
IBMBCEDF 
IBMBCYXX 
IBMBCMPX 
IBMBCMPF 
IBMBCUIF 
IBMBCTHD 
IBMBCODE 
IBMBCRXB 
IBMBCRXB 
IBMBCWDH 
IBMBCGPA 
IBMBCACA 
IBMBCACA 
IBMBCACA 
IBMBCACA 
IBMBCPBF 
IBMBCEDB 
IBMBSCVA 
IBMBCKZP 
IBMBCWZH 
IBMBCGTA 
IBMBCOZE 
IBMBCKZP 
IBMBSCVA 



IBMBPRC1 

IBMBKST1 

IBMBKST1 

IBMBKCP1 

IBMBKCP1 

♦SAMPLE1 

♦SAMPLEl 

♦SAMPLE1 

IBMBSEOl 

+SAMPLE2 

♦SAMPLE2 

♦SAMPLE2 

♦SAMPLE2 

♦SAMPLE2 
$UNRESOLVED(W) 
$UNRESOLVED(W) 
$ UNRESOLVED (W) 

IBMBOCL1 

IBMBERR1 
$UNRESOLVED(W) 

IBMBOCL1 

IBMBEER1 

IBMBCH01 

IBMBCH01 

IBKBCK01 

IBMBCHOl 

IBMBCH01 

IBMBCHOl 
$UNRESOLVED(W) 
$UNRESOLVED(W) 
$UNRESOLVED(W) 
$UNRESOLVED(W) 

IBMBCQ01 

IBMBCT01 

IBMBCO01 
$UNRESOLVED(tf) 
$UNRESOLVED(W) 
$UNRESOLVED(W) 
$UNRESOLVED(W) 
$UNRESDLVED(W) 
$ONRESOLVED(W) 
$(JNRESOLVED(W) 
$UNRESOLVED(tf) 
$UNRESOLVED(W) 
$UNRESOLVED(W) 

IBMBSCV1 

IBMBCK01 
$UNRESOLVED(W) 

IBMBCGT1 

IBMBCO01 

IBMBCK01 

IBMBSCV1 



9 

ft 



N 

H- 
3 

O 

i 

0) 



*0 




LOCATION REFERS TO SYMBOL IN CONTROL SECTION 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION 



22F4 


IBMBCEFX 


$UNRESOLVED(W) 


2304 


IBMBCHFP 


IBMBCH01 


25EC 


IBMBSCVA 


IBMBSCV1 


2C9C 


IBMBSAOA 


$ UNRESOLVED (W) 


2C94 


IBMBSFOA 


$UNRESOLVED(W) 


2C98 


IBMBSPOA 


IBMBSPOl 


2CA0 


IBMBSCOA 


$UNRESOLVED(W) 


2C80 


IBMBSIST 


$ UNRESOLVED (W) 


2F00 


IBMBSPLB 


IBMBSPL1 


2EF8 


IBMBOCLA 


IBMBOCL1 


37B0 


IBMBERCA 


$UNRESOLVED(W) 


39C4 


IBMBRIOB 


$UNRESOLVED(W) 


39CC 


IBMBSCPA 


$UNRESOLVED(W) 


41 AC 


IBMBCACA 


$UNRESOLVED(W) 


41A4 


IBMBCZCA 


$UNRESOLVED(W> 


419C 


IBMBSIST 


$UNRESOLVED(W) 


4564 


IBMBCKDP 


IBMBCK01 


4574 


IBMBCMPP 


$UNRESOLVED(W) 


1*580 


IBMBCHXE 


IBMBCH01 


4588 


IBMBCHFE 


IBMBCH01 


459C 


IBMBCMPE 


$UNRESOLVED(W) 


4590 


IBMBCPBE 


$UNRESOLVED(W) 



LOCATION 20 REQUESTS CUMULATIVE PSEUDO RE3ISTER LEN3TH 
ENTRY ADDRESS 00 
TOTAL LENGTH 49C0 



22FC 


IBMBCHFD 


IBMBCH01 


230C 


IBMBCHFE 


IBMBCH01 


2C8C 


IBMBSAIA 


$UNRESOLVED(W) 


2C84 


IBMBSFIA 


$ UNRESOLVED (W) 


2C88 


IBMBSPIA 


$UNRESOLVED(W) 


2C90 


IBMBSCIA 


$UNRESOLVED(W) 


2CA4 


IBMBSBOA 


$UNRESOLVED(W) 


2EFC 


IBMBSPLA 


IBMBSPL1 


2F04 


IBMBSPLC 


IBMBSPL1 


2F0C 


IBMBCODP 


IBMBCO01 


37B4 


IBMBEEFA 


IBMBEEF1 


39C8 


IBMBRIOC 


$UNRESOLVED(W) 


3ACC 


IBMBSIST 


$UNRESOLVED(W) 


41A8 


IBMBCBGA 


$UNRESOLV£D(W) 


41A0 


IBMBCXOA 


$UNRESOLVED(W) 


4560 


IBMBCHXP 


IBMBCH01 


4568 


IBMBCHFP 


IBMBCH01 


457C 


IBMBCMPP 


$ UNRESOLVED (W) 


4584 


IBMBCODE 


IBMBCO01 


4594 


IBMBCMPE 


$uNRESOLVED(tf) 


458C 


I BMBCPBP 


$UNRESOLVED(W) 


4598 


IBMBCCSA 


IBMBCCS1 



****GO 



DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 



<b 



SAMPLE PROGRAM: DATE = 73/04/13, TIME = 21.18.17 
END SAMPLE PROGRAM 



Appendix 6: Running undez a Virtual Storage Operating 

System(OS/VS) 



0S/VS1 and 0S/VS2 are the virtual-storage 
equivalents of OS/MFT and OS/MVT 
respectively. In general, a program that 
compiles and executes successfully under 
OS/MFT or OS/MVT will do so under OS /VS. 

OS/VS has the advantage that the size of 
the partition or region used by the program 
is not limited by the amount of real 
storage available. in the case of PL/I 
programs, partitions or regions large 
enough to give maximum efficiency during 
both compilation and execution can be used, 
and the segmentation of programs to fit 
restricted amounts of storage becomes 
unnecessary. 

Virtual partitions or regions can be 
allocated in multiples of 64K bytes. The 
amount of real storage available to a 
program at any time is under the control of 
the Operating System, and cannot be 
specified by the programmer. The storage 
requirements given below refer to the 
amounts of virtual storage available. 

The compiler will run in the minimum 
virtual partition or region size of 64K 
bytes. However, increased efficiency can 
be obtained by using a partition or region 
size large enough to prevent the compiler 
from using its spill file. The use of 
partition or region sizes in excess of 
those required to prevent the compiler from 
using its spill file may cause a slight 
degradation in performance, but this will 



not usually be significant unless the 
amount of real storage allocated by the 
operating system is small. 

It is inadvisable to limit the amount of 
storage available to the compiler by 
specifying the SIZE option. This option 
should be used only if ycu require tc 
reserve space for other routines, such as 
ones that invoke the compiler dynamically. 
In any case, the compiler requires at least 
52k bytes of storage under VSl and at least 
54K bytes under VS2 . 

The sizes of records en the compiler 
spill file depend on the amount of storage 
available to the compiler. Figure G-l 
gives record sizes under VSl. For VS2, the 
specified storage size limits should be 
increased by 2K bytes. 



Storage (bytes) Record size (bytes) 



52-62K 
62-78K 
78-84K 
Over 84K 



1091 
1691 
3491 
4051 



Figure G-l. Compiler spill file record 
sizes 



Note that the 2311 Disk Storage Unit is 
not supported by OS/VS. 
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Index 



Where more than one page reference is given, the major reference is first. 



A page reference to a paragraph split between 
two pages. 



6LKLBDSN parameter in cataloged 
procedure 15 



* parameter of DD statement 11 

* PROCESS statement 5 



%INCLUDE statement 44 
%PAGE statement 26,35 
%SKIP statement 26 r 35 



abbreviated form of compiler options 21 
absolute addresses 49,70 
access method services 133 
access methods 80,131 
access speed 

improving, for INDEXED data sets 110 

improving, for REGIONAL data sets 118 
accessing a VSAM data set 

entry sequenced data set 137 

key sequenced data set 136 
addressing 4 9 

advanced checkpoint/restart 189 
aggregate length table 37 
AGGREGATE option 22 
ALIAS statement (linkage editor) 58 
aliases 58 
American National Standard control 

characters (see ANS) 
American Standard Code for Information 

Interchange (see ASCII) 
AMP parameter 137 

ANS (American National standard) control 
characters 

printers 95,105 

punched card devices 105 

source listing 26 

specifying in JCL 197 
APAR (Authorized Program Analysis 

Report) 207 
areas 199 

argument passed to main procedure 31 
arguments in checkpoint/restart 200 
arrays 

length table 37 

mapping 17 

maximum number of dimensions 199 
ASCII (American Standard code for 
Information Interchange) 74,75,194 

for paper tape, specifying 194 

option of ENVIRONMENT attribute 74 

records 76 
Assembler language linkage 165 

abnormal termination 169,173 

Assembler-PL/I -Assembler 173 

calling Assembler routines from 
PL/I 169 



two pages will refer to the first of the 

Assembler language linkage (continued) 

calling PL/I procedures from 
Assembler 170 

error handling 173 

establishing PL/I environirent 165 

invoking PL/ I procedure 165 

linkage conventions 165 

no main PL/I procedure 17 

use of register 12 169 
Assembler language listing 4 
ASSEMBLER option 174 

asterisk (*) parameter of DD statement 11 
ATTACH macro instruction 45 
attribute listing 22,29,36 
ATTRIBUTES option 22 
automatic library call 

DD statement for 51 

introduction 50 

main discussion 52 

suppressing 54,69 

use of by loader 64,69 

use of by programmer 141 
auxiliary storage (see storage) 



base library (SYSl.PLIEASE) 53,150 
basic access technique 81 
Basic Direct Access Method (BEAM) 81 
Basic Indexed Sequential Access Methcd 

(BISAM) 81 
Basic Sequential Access Method (BSAM) 81 
batched compilation 41,62 
BCD (Binary Coded Decimal) 

compiler options 22 

magnetic tape translation 88,197 
BDAM (Basic Direct Access Method) 81 
Binary Coded Decimal (see BCD) 
BISAM (Basic indexed Sequential Access 

Method) 81 
blanks, removal of 17 

BLKSIZE option of ENVIRONMENT attribute 74 
BLKSIZE subparameter of DCB 

parameter 194,74 
block size 194 

CONSECUTIVE data sets 
record I/O 101 ,103 
stream I/O 91,92 

INDEXED data sets 110 

introduction 9 

PRINT files 95 

REGIONAL data sets 118 

specifying 74.194 

system output device (SYSOUT) 13 
blocking (in general) 74 
boundary alignment 17 
branching, trace table showing 160 
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REREAD option 79 
RES option (loader) 69 
resident control phase 15 
resident library (see library subroutines) 
restart 189 
RESTART parameter 190 
return codes 

checkpoint/ rest art 18 9 

compiler 41 

PL/I program 163 

PLIRETC restriction 203 

return code 0004 from linkage editor 56 

sort/merge 177,178 
returned values 201 



RKP subparameter of DCB paraireter 112,197 
RLD (relocation dictionary) 49 
root segment 59 



save areas 165 
scheduling time 48 
scheduling, chained 80,196 
segment, root 59 
sequence numbering 

compiler options 28 

for preprocessor 43,4 5 
SEQUENCE option 28 
sequence set (VSAM) 131 
sequential data sets 77 
SER subparameter 10 
serial number, volume (see volume serial 

number) 
severity of messages 

compiler 24 

linkage editor 56 
shared library cataloged procedures 213 
SIGNAL statement 161 
SIZE option 

compiler 28, 41 

linkage editor 54 

loader 70 
SKIP option/format item 95 
SMESSAGE option 26 
SNAP option 160 
sort/merge 177 

arguments 179 

data sets 178 

entry names 177 

examples 181 

invoking 179 

message listing options 181 

multiple invocation 180 

sorting techniques 181 

storage requirements 177 

user exits 177 
SORTCKPT 179,180 
SORTIN 178,180 
SORTLIB 179 
SORTOUT 179,180 
SORTWK 179,180 
SOURCE option 29 
source program 

character set specification 22 

data code specification 22 

data set 19 

listing .25,29 

compiler, option for 29 
nesting level 27 
record numbering 25,27,28 
statement numbering 29,35 
source statement library 44 
SPACE parameter 

accessing data sets 10 

for direct-access devices 89 

for library 142 

for linkage editor output 52 

for standard data sets 19 

introduction 9 
spanned record s 9,75,196 
SPIE option 32 
spill file 20 
STACK subparameter of DCB parameter 197 
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stacker selection 105,85 

specifying in JCL 197 
STAE option 32 
standard files 98 
statement numbers 

compiler option 29 

in messages 25 

method of numbering 35 

trace of 160 
statement, maximum number of 204 

restrictions 204 
static internal control section 

description 48 

length 39 

listing 4 
static storage map 26 
STEPLIB DD statement 142 
STMT option 29 
storage 

addressing 4 9 

allocation 17 

auxiliary, economy 

blocking PRINT files 96 
in INDEXED data sets 111 
in REGIONAL data sets 118 
suppressing automatic library 

call 54 
using loader 48 
using track overflow 196 

buffers 80 

dumps 161 

for Assembler language linkage 165,169 

for checkpoint/restart data set 189 

for compilation 28 

for direct- access devices 89 

for execution 31 

for library data sets 142 

for linkage editor 52 

for loader 64,70 

for sort/merge 177 

for standard data sets 18 

insufficient available 28 

linkage editor 54 

optimization 28 

overlaying (see overlaying) 

requirements in general 28 

virtual 1 
STORAGE option 29 
stream-oriented input/output 

access method 81 

defining data sets 91 
STRINGRANGE condition 160 
structures 

length table 37 

mapping 17 
stub, link-edit 63 
subroutines, library (see library 

subroutines) 
SUBSCRIPTRANGE condition 159 
SUBSTR pseudo variable as source of 

error 160 
supervisor (see operating system) 
symbolic parameter in cataloged 

procedures 150 
syntax analysis stage 17 
syntax checking option 

compiler option 29 

suppression of 158 



SYNTAX option 29 
SYSCIN 19 
SYSIN 19,98 
SYSLIB 

linkage editor 52 

loader 67 

multitasking programs 150 

preprocessing 20 
SYSLIN 42 

compiler output 19 

linkage editor input 51 

loader input 66 
SYSLMOD 51 
SYSLOUT 67,70 
SYSOUT parameter 11 

INDEXED data set restriction 110 
SYSPRINT 

associated with terminal 30 

compiler data set 20 

linkage editor data set 53 

loader data set 67,70 

standard PL/I file 98 
SYS PUNCH 19 
system failure 160 

system output device (see SYSOUT parameter) 
system procedure library 

(SYS1.PR0CLIB) 149 
system program library (SYSl.LINKLIB) 142 
SYSUT1 

compiler data set 20 
SYSl.LINKLIB (system program library) 142 
SYSl.PLIBASE 63,79 
SYSl.PLIBASE (base libary) 53,151 
SYSl.PIICMIX 63 

SYS1.PLITASK (multitasking library) 53,150 
SYSl.PROCLIB (system procedure 
library) 141 ,149 



tab control table 98 

tab position specification and defaults 98 

tape, magnetic (see magnetic tapes) 

TCA (task communications area) 163 

TCAM (Telecommunications Access 

Method) 81,124 
Telecommunications Access Method 

(TCAM) 81,124 
teleprocessing 124 
Teletype code for paper tape 194 
temporary workspace 

essential parameters 52 

for compiler 20 

for linkage editor 52 
TERMINAL option 30 
terminal processing (see TSO) 
termination 

in Assembler-PL/I linkage 169,173 

of compilation, dump option 24 

of execution, abnormal 159 

of execution, by request 162 
testing (see checkout, program) 
text (TXT) , description of 48 
text, source (definition) 15 
Time Sharing Option (see TSO) 
time taken for compilation 35 
timer feature 35 
trace information 160,161 

compiler option 24 
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trace information (continued) 

execution-time option 34 
track (definition) 8 9 
track index 107 
track overflow, specifying 196 
trailer label 77 
transfer vector 213 
transient control phase 15 
TRANSIENT files 77 

transient library (see library subroutines) 
translation stages 17 
TRANSMIT condition, suppressing 196 
troubleshooting (see checkout, program; 

problem determination) 
TRTCH subparameter of DCB parameter 88,197 
TSO (Time sharing Option) 

checkpoint/restart restriction 18 9 

conversational checkout 157 

introduction 1 

line numbers 27 

storage requirements 2 9 

terminal output option 30 



VSAM data sets (continued) 

catalogs 131 

compatibility interface 137 

control area 131 

control interval 131 

device restriction 131 

index data set 131 

index set 131 

logical record 131 

passwords 138 

sequence set 131 

sharing 138 
VSl (Virtual Storage) 

introduction 1 
VS2 (Virtual Storage) 

introduction 1 
VTOC (volume table of contents) 77 



WAIT statement 205 

weak external reference 38 

workfiles, temporary 150 



76 
81,96 

10 
8,78 

103 



U-format records 76 
unblocked records 75 
undefined- length records 
UNDEFINEDFILE condition 
UNIT parameter 

accessing a data set 

creating a data set 
unlabeled data sets 77 
unlabeled magnetic tapes 
unnamed data sets 74,10 
updating data 10 
user exit points 177 

user information (see argument passed to 
main procedure) 



V- format records 75 

validity check, write, specifying 196 

variable-length records 75,183 

variables storage map 40 

varying -length strings, sorting 178 

VB- format records 75 

VBS -format records 75 

version number of compiler 35 

virtual storage 1 

volume 

definition of term 9 
labeling 77 

VOLUME parameter 

(see also volume serial number) 
accessing data sets (general) 10 
creating data sets (general) 10 

volume serial number 

accessing REGIONAL data sets 120 
creating CONSECUTIVE data sets 
record I/O 101,103 
stream I/O 91 
creating INDEXED data sets 110 
creating REGIONAL data sets 118 
in volume label 77 

volume table of contents (VTOC) 77 

VS- format records 75 

VSAM (Virtual Storage Access Method) 131 

VSAM data sets 131 



XCAL option (linkage editor) 55 
XCTL macro instruction 4 5 
XREF option 

compiler 30 

linkage editor 55 



1403 Printer control characters (see 
printers) 



2400-series tape drives, conversion 
feature 197 



2540 Card Read Punch control characters 95 



3505 Card Reader 84 



3525 Card Punch 84 



48-character set 17,22 



60-character set 17,22 



7- track magnetic tape (see magnetic tapes) 



9-track magnetic tape (see magnetic tapes) 
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